skill-name/
└── SKILL.md

skill-name/
├── SKILL.md           # Main skill file (required)
├── references/        # Additional documentation
│   └── api-guide.md
├── scripts/           # Helper scripts
│   └── helper.py
└── assets/            # Templates, examples
    └── template.txt

---
name: my-skill-name
description: Clear description of what this skill does. Include trigger keywords like keyword1, keyword2, keyword3 so the agent knows when to activate this skill.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

# Skill Title

## Purpose
Brief explanation of what this skill provides.

## When to Use
- Scenario 1 (include keywords)
- Scenario 2 (include keywords)
- Scenario 3 (include keywords)

## Process

### 1. Understand the Request
How to analyze what the user needs.

### 2. Gather Context
What information to collect.

### 3. Provide Solution
Step-by-step approach.

## Examples

### Example 1: Basic Usage
**Request:** "Help me with X"
**Response:** [How skill handles it]

## Best Practices
- Practice 1
- Practice 2

## Common Pitfalls
- Avoid X, do Y instead

description: Expert in Next.js App Router, server components, and React Server Components. Use when user mentions Next.js, RSC, App Router, server actions, or React server-side patterns.

description: Helps with Next.js

name: fastapi-expert
description: FastAPI web framework expert covering routing, dependencies, Pydantic models, async endpoints, and OpenAPI generation. Triggers on FastAPI, Python API, Pydantic, async web.

name: component-generator
description: Generate React components with TypeScript, tests, and stories. Triggers on generate component, create component, scaffold component.

name: security-auditor
description: Security code review for common vulnerabilities including XSS, SQL injection, and OWASP Top 10. Triggers on security review, audit code, find vulnerabilities.

name: release-helper
description: Automate release workflows including changelog generation, version bumping, and git tagging. Triggers on release, changelog, version bump, tag release.

name: csv-processor
description: Parse, transform, and analyze CSV files. Convert between CSV, JSON, and other formats. Triggers on CSV, parse CSV, convert CSV.

your-repo/
├── skills/
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
└── README.md

# Users install from your repo
npx add-skill your-username/your-repo

# List available skills
npx add-skill your-username/your-repo --list

# Install specific skill
npx add-skill your-username/your-repo --skill my-skill

# Direct link to skill
npx add-skill https://github.com/user/repo/tree/main/skills/my-skill