Skill File Anatomy

Every Skill consists of a core SKILL.md file and an optional resources/ directory.

Full Structure

my-skill/
├── SKILL.md              # Required: Skill entry file
└── resources/            # Optional: Additional resources
    ├── examples.md       # Usage examples
    ├── reference.md      # Reference material
    ├── templates/        # Template files
    │   └── report.md
    └── scripts/          # Helper scripts
        └── validate.sh

SKILL.md Detail

SKILL.md uses Markdown + YAML Frontmatter format:

---
name: my-awesome-skill
description: |
  Short one-line summary of what this Skill does.
  Used for trigger matching — be specific and distinct.
metadata:
  type: workflow
  version: "1.0"
triggers:
  - "do the thing"
  - "run awesome workflow"
  - "awesome skill"
allowed-tools:
  - Bash
  - Read
  - Write
---

# My Awesome Skill

## When to Use
- Scenario A: ...
- Scenario B: ...

## Workflow
1. Step one — do this
2. Step two — do that
3. Step three — verify

## Output Format
- Result should include...
- Always check...

## Notes
- Edge case: ...
- Limitation: ...

Frontmatter Fields

Field	Required	Description
name	Yes	kebab-case unique identifier
description	Yes	One-line summary used for trigger matching
triggers	No	Additional trigger keyword list
allowed-tools	No	Restrict available tools for this Skill
metadata.type	No	Skill category

Prompt Section

All Markdown content after the Frontmatter is the Prompt section — the core of the Skill describing its behavior, workflow, and domain knowledge.

Writing Guidelines

• Clear boundaries: Explicitly state when to use and when NOT to use
• Step-by-step: Numbered workflow steps
• Output spec: Describe expected output format
• Anti-patterns: List common mistakes to avoid

Resources Directory

Files under resources/ are not auto-loaded into context but can be read by Claude Code on demand.

• Good for: Long reference docs, templates, data files
• Bad for: Core workflow descriptions (put those in SKILL.md)

Next Steps

• Frontmatter Config — Deep dive into Frontmatter fields
• Prompt Design — Prompt writing best practices