Skill Structure

skill-name/
├── SKILL.md              # Required - frontmatter + instructions
├── scripts/              # Optional - executable code (Python/Bash)
├── references/           # Optional - docs loaded on-demand
└── assets/               # Optional - templates, images, fonts

SKILL.md Format

---
name: skill-name
description: [Self-contained workflow summary — see guidelines below]
---
# Instructions here (markdown body)

Name: Short, hyphen-case identifier. Should be descriptive but concise (max 64 chars).

Description: Agent sees this + the name before loading. Must be self-contained with:

• What workflow/capabilities it provides
• "Use proactively when" trigger contexts
• 3-5 concrete examples

CRITICAL: The description field is the primary trigger mechanism.

Skills are SOPs/workflows, NOT agents. DO NOT use role descriptions like "You are a..." or "[Role] expert."

Before loading, the agent sees only the name and description in <available_skills>:

<available_skills>
  <skill>
    <name>skill-name</name>
    <description>...</description>
  </skill>
</available_skills>

The description must be self-contained — agents won't load a skill just to "see what it does."

Name + description should work together:

• Name: Short, hyphen-case identifier (e.g., typescript-advanced)
• Description: Self-contained workflow summary with capabilities, triggers, and examples

Description pattern (LLM-optimized):

---
name: skill-name
description: |-
  [Action verb/capabilities]. Use for [specific cases]. Use proactively when [contexts].
  
  Examples:
  - user: "query" → action
  - user: "query" → action
---

Dense, machine-parseable, specific. Avoid prose.

CRITICAL YAML SYNTAX: Multi-line descriptions with examples MUST use literal block scalar (|-). The hyphen strips the trailing newline. Do NOT use plain YAML with unquoted colons or lists:

# ❌ WRONG - breaks YAML parsing
description: Handle plugins. Examples:
- user: "..." → action

# ✅ CORRECT - use |- for multi-line
description: |-
  Handle plugins.
  
  Examples:
  - user: "..." → action

Example:

---
name: typescript-advanced
description: |-
  Handle TypeScript 5.9 advanced typing, generics, strict configs, type errors, migrations,
  erasable syntax compliance, and test writing. Use proactively for complex generics,
  conditional types, utility types, TS compiler config, or test authoring.
  
  Examples:
  - user: "Create a type-safe event emitter" → implement with generics and mapped types
  - user: "Migrate to strict TypeScript" → add discriminated unions, exhaustive checks
  - user: "Build typed API client from OpenAPI" → generate request/response types with inference
  - user: "Write unit tests" → create strict, typed tests with realistic fixtures
---

Requirements:

• Start with action verb (NOT "You are" or "[Role] expert")
• List specific capabilities (vague "helps with X" = ignored)
• Include "Use proactively when" trigger contexts
• Provide 3-5 concrete user: "..." → ... examples
• Use |- literal block scalar for multi-line descriptions (plain YAML with lists/colons breaks parsing)
• Dense, LLM-parseable — description alone must justify loading

Reduce redundancy: Don't repeat description content in SKILL.md body.

Bundled Resources

MUST NOT include: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or other auxiliary docs. Skills contain only what the agent needs to do the job.