Skill Md Anatomy — Claude Code Guide

SKILL.md is a contract, not a notebook

SKILL.md should explain the purpose, trigger, input, process, result, and prohibitions of a skill. Read it as a workflow description that another person can review, version, and maintain.

Frontmatter fields and invocation syntax can change between versions, so verify the current form through /help and the current documentation.

Minimal anatomy

---
name: issue-analysis
description: Prepare TASK_SPEC.md from an issue and evidence.
when_to_use: When analysis must precede implementation.
---

# Purpose

## Input

## Steps

## Result

## Prohibitions

## Verification

What belongs in a skill

Part	Question
Name and description	What concrete value does it provide?
Trigger	When should it run?
Input	Which issues, files, or arguments are required?
Process	Which steps run, and in what order?
Result	Which artifact or report is produced?
Prohibitions	What must it never do?
Tools	What is the minimum required capability?

Issue-analysis example

Input: issue text, file references, and logs when needed;
Process: find related modules, define goal, scope, non-goals, and risks;
Result: TASK_SPEC.md with evidence and open questions;
Prohibition: do not edit code or begin implementation;
Verification: goal, scope, non-goals, acceptance, and verification are present.

Permissions must match purpose

An analytical skill usually needs reading and search. Do not grant it project-wide editing access without a concrete reason. Run a new or unverified skill manually first, then add automation only after its behavior is stable.

Review someone else’s SKILL.md

Identify its trigger.
Check its input.
Find the expected artifact.
Read prohibitions and available tools.
Confirm that permissions match the role.
Compare the workflow with repository patterns.