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

---
name: skill-name
description: [Self-contained workflow summary — see guidelines below]
---

**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>`:

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):**
```yaml
---
name: skill-name
description: |-
  [Action verb/capabilities]. Use for [specific cases]. Use proactively when [contexts].
  
  Examples:
  - user: "query" → action
  - user: "query" → action
---

undefined

**Example:**
```yaml
---
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
---

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

undefined

Create `SKILL.md` with frontmatter:

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

**Description template example:**
```yaml
---
name: typescript-advanced
description: |-
  Handle TypeScript 5.9 advanced typing, generics, strict configs, type errors, migrations,
  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
---

cd my-skill
mkdir scripts references assets  # only create what you'll actually use

{
  "permission": {
    "skill": { "*": "deny", "my-skill": "allow" }
  }
}