skill-master

Original source / Raw SKILL.md

---
name: skill-master
description: "Agent Skills authoring. Covers SKILL.md format, frontmatter, folders, docs ingestion. Keywords: agentskills.io, SKILL.md."
version: "1.2.3"
release_date: "2026-01-23"
metadata:
  author: itechmeat
---

# Skill Master

This skill is the entry point for creating and maintaining Agent Skills.

**Language requirement:** all skills MUST be authored in English.

## Quick Navigation

- New to skills? Read: `references/specification.md`
- SKILL.md templates? See: `assets/skill-templates.md`
- Advanced features (context, agents, hooks)? Read: `references/advanced-features.md`
- Creating from docs? Read: `references/docs-ingestion.md`
- Validation & packaging? See `scripts/`

## When to Use

- Creating a new skill from scratch
- Updating an existing skill
- Creating a skill by ingesting external documentation
- Validating or packaging a skill for distribution

## Skill Structure (Required)

```
my-skill/
├── SKILL.md          # Required: instructions + metadata
├── README.md         # Optional: human-readable description
├── metadata.json     # Optional: extended metadata for publishing
├── references/       # Optional: documentation, guides, API references
├── examples/         # Optional: sample outputs, usage examples
├── scripts/          # Optional: executable code
└── assets/           # Optional: templates, images, data files
```

### Folder Purposes (CRITICAL)

| Folder        | Purpose                                    | Examples                                                |
| ------------- | ------------------------------------------ | ------------------------------------------------------- |
| `references/` | **Documentation** for agents to read       | Guides, API docs, concept explanations, troubleshooting |
| `examples/`   | **Sample outputs** showing expected format | Output examples, usage demonstrations                   |
| `assets/`     | **Static resources** to copy/use           | Document templates, config templates, images, schemas   |
| `scripts/`    | **Executable code** to run                 | Python scripts, shell scripts, validators               |

### When to Use Each

**Use `references/` for:**

- Detailed documentation about concepts
- API references and usage guides
- Troubleshooting and FAQ
- Anything the agent needs to **read and understand**

**Use `examples/` for:**

- Sample outputs showing expected format
- Usage demonstrations
- Before/after comparisons
- Anything showing **what the result should look like**

**Use `assets/` for:**

- Document templates (markdown files to copy as starting point)
- Configuration file templates
- Schema files, lookup tables
- Images and diagrams
- Anything the agent needs to **copy or reference verbatim**

**IMPORTANT**: Templates belong in `assets/`, examples in `examples/`, documentation in `references/`.

## Frontmatter Schema

Every `SKILL.md` MUST start with YAML frontmatter:

```yaml
---
name: skill-name
description: "What it does. Keywords: term1, term2."
metadata:
  author: your-name
  version: "1.0.0"
---
```

**Field order:** `name` → `description` → `license` → `compatibility` → `metadata` → other fields

### Required Fields

| Field       | Constraints                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| name        | 1-64 chars, lowercase `a-z0-9-`, no `--`, no leading/trailing `-`, must match folder name   |
| description | 1-1024 chars (target: 80-150), describes what skill does + when to use it, include keywords |

### Optional Fields (Top Level)

| Field         | Purpose                                           |
| ------------- | ------------------------------------------------- |
| license       | License name or reference to bundled LICENSE file |
| compatibility | Environment requirements (max 500 chars)          |
| metadata      | Object for arbitrary key-value pairs (see below)  |

### metadata Object (Common Fields)

| Field         | Purpose                                          |
| ------------- | ------------------------------------------------ |
| author        | Author name or organization                      |
| version       | **Skill version** (semver format, e.g., "1.0.0") |
| argument-hint | Hint for autocomplete, e.g., `[issue-number]`    |

**IMPORTANT**: `version` in `metadata` is the **skill version**. If you reference external product docs, track that version separately (e.g., in README.md or metadata.json).

### Optional Fields (Claude Code / Advanced)

| Field                    | Purpose                                                                    |
| ------------------------ | -------------------------------------------------------------------------- |
| disable-model-invocation | `true` = only user can invoke (via `/name`). Default: `false`              |
| user-invocable           | `false` = hidden from `/` menu, only agent can load. Default: `true`       |
| allowed-tools            | Space-delimited tools agent can use without asking, e.g., `Read Grep Glob` |
| model                    | Specific model to use when skill is active                                 |
| context                  | Set to `fork` to run in a forked subagent context                          |
| agent                    | Subagent type when `context: fork`, e.g., `Explore`, `Plan`                |
| hooks                    | Hooks scoped to skill's lifecycle (see agent documentation)                |

### Invocation Control Matrix

| Frontmatter                      | User can invoke | Agent can invoke | Notes                                   |
| -------------------------------- | --------------- | ---------------- | --------------------------------------- |
| (default)                        | ✅ Yes          | ✅ Yes           | Description in context, loads when used |
| `disable-model-invocation: true` | ✅ Yes          | ❌ No            | For manual workflows with side effects  |
| `user-invocable: false`          | ❌ No           | ✅ Yes           | Background knowledge, not a command     |

### Variable Substitutions

Available placeholders in skill content:

| Variable               | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `$ARGUMENTS`           | All arguments passed when invoking the skill             |
| `${CLAUDE_SESSION_ID}` | Current session ID for logging or session-specific files |

If `$ARGUMENTS` is not in content, arguments are appended as `ARGUMENTS: <value>`.

Example:

```yaml
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.
```

### Dynamic Context Injection

Use `!`command`` syntax to run shell commands before skill content is sent to the agent:

```markdown
## Pull request context

- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

## Your task

Review this pull request...
```

The command output replaces the placeholder, so the agent receives actual data.

## metadata.json (Optional)

For publishing or extended metadata, create `metadata.json`:

```json
{
  "version": "1.0.0",
  "organization": "Your Org",
  "date": "January 2026",
  "abstract": "Brief description of what this skill provides...",
  "references": ["https://docs.example.com", "https://github.com/org/repo"]
}
```

**Fields:**

- `version` — Skill version (semver)
- `organization` — Author or organization
- `date` — Publication date
- `abstract` — Extended description (can be longer than frontmatter)
- `references` — List of source documentation URLs

### Name Validation Examples

```yaml
# Valid
name: pdf-processing
name: data-analysis
name: code-review

# Invalid
name: PDF-Processing  # uppercase not allowed
name: -pdf            # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed
```

### Description Rules

**Purpose:** Tell the LLM what the skill does and when to activate it. Minimize tokens — just enough for activation decision.

**Formula:**

```
[Product] [core function]. Covers [2-3 key topics]. Keywords: [terms].
```

**Constraints:**

- Target: 80-150 chars
- Max: 300 chars
- No marketing ("powerful", "comprehensive", "modern")
- No filler ("this skill", "use this for", "helps with")
- No redundant context (skip "for apps", "for developers")

**Good examples:**

```yaml
description: "Turso SQLite database. Covers encryption, sync, agent patterns. Keywords: Turso, libSQL, SQLite."

description: "Base UI unstyled React components. Covers forms, menus, overlays. Keywords: @base-ui/react, render props."

description: "Inworld TTS API. Covers voice cloning, audio markups, timestamps. Keywords: Inworld, TTS, visemes."
```

**Poor examples:**

```yaml
# Too vague
description: "Helps with PDFs."

# Too verbose
description: "Turso embedded SQLite database for modern apps and AI agents. Covers encryption, authorization, sync, partial sync, and agent database patterns."

# Marketing
description: "A powerful solution for all your database needs."
```

**Keywords:** product name, package name, 3-5 terms max.

## How Skills Work (Progressive Disclosure)

1. **Discovery**: Agent loads only `name` + `description` of each skill (~50-100 tokens)
2. **Activation**: When task matches, agent reads full `SKILL.md` into context
3. **Execution**: Agent follows instructions, loads referenced files as needed

**Key rule:** Keep `SKILL.md` under 500 lines. Move details to `references/`.

## Creating a New Skill

### Step 1: Scaffold

```bash
python scripts/init_skill.py <skill-name>
# Or specify custom directory:
python scripts/init_skill.py <skill-name> --skills-dir skills
```

Or manually create:

```
<skills-folder>/<skill-name>/
├── SKILL.md
├── references/   # For documentation, guides
└── assets/       # For templates, static files
```

### Step 2: Write Frontmatter

```yaml
---
name: <skill-name>
description: "[Purpose] + [Triggers/Keywords]"
---
```

### Step 3: Write Body

Recommended sections:

- When to use (triggers, situations)
- Quick navigation (router to references and assets)
- Steps / Recipes / Checklists
- Critical prohibitions
- Links

### Step 4: Add References (documentation)

For each major topic, create `references/<topic>.md` with:

- Actionable takeaways (5-15 bullets)
- Gotchas / prohibitions
- Practical examples

### Step 5: Add Assets (if needed)

For templates or static resources, create `assets/<resource>`:

- Document templates
- Configuration templates
- Schema files

### Step 6: Validate

```bash
python scripts/quick_validate_skill.py <skill-path>
```

## Creating a Skill from Documentation

When building a skill from external docs, use the autonomous ingestion workflow:

### Phase 1: Scaffold

1. Create skill folder with `SKILL.md` skeleton
2. Create `plan.md` for progress tracking
3. Create `references/` directory

### Phase 2: Build Queue

For each doc link:

- Fetch the page
- Extract internal doc links (avoid nav duplicates)
- Prioritize: concepts → API → operations → troubleshooting

### Phase 3: Ingest Loop

For each page:

1. Fetch **one** page
2. Create `references/<topic>.md` with actionable summary
3. Update `plan.md` checkbox
4. Update `SKILL.md` if it adds a useful recipe/rule

**Do not ask user after each page** — continue autonomously.

### Phase 4: Finalize

- Review `SKILL.md` for completeness
- Ensure practical recipes, not docs mirror
- `plan.md` may be deleted manually after ingestion

## Critical Prohibitions

- Do NOT copy large verbatim chunks from vendor docs (summarize in own words)
- Do NOT write skills in languages other than English
- Do NOT include project-specific secrets, paths, or assumptions
- Do NOT keep `SKILL.md` over 500 lines
- Do NOT skip `name` validation (must match folder name)
- Do NOT use poor descriptions that lack trigger keywords
- Do NOT omit product version when creating skills from documentation

## Version Tracking

When creating or updating a skill from external documentation:

1. Add `version` field in frontmatter for product version:

   ```yaml
   ---
   name: my-skill
   description: "..."
   version: "1.2.3"
   ---
   ```

2. Optionally add `release_date` if known:

   ```yaml
   ---
   name: my-skill
   description: "..."
   version: "1.2.3"
   release_date: "2025-01-21"
   ---
   ```

3. Create `README.md` with:
   - Skill overview (1-2 sentences)
   - Usage section (when to use)
   - Links section (standardized format)

**README.md Links section format:**

```markdown
## Links

- [Documentation](https://example.com/docs)
- [Changelog](https://example.com/changelog)
- [GitHub](https://github.com/org/repo)
- [npm](https://www.npmjs.com/package/name)
```

Include only applicable links. Order: Documentation → Changelog/Releases → GitHub → Package registry.

Example frontmatter:

```yaml
---
name: turso
description: "Turso embedded SQLite database..."
version: "0.4.0"
release_date: "2025-01-05"
---
```

This helps track when the skill was last updated and against which product version.

## Validation Checklist

- [ ] `name` matches folder name
- [ ] `name` is 1-64 chars, lowercase, no `--`
- [ ] `description` is 1-1024 chars, includes keywords
- [ ] `SKILL.md` under 500 lines
- [ ] Documentation in `references/`, templates in `assets/`
- [ ] All text in English

## Scripts

| Script                    | Purpose                                                 |
| ------------------------- | ------------------------------------------------------- |
| `init_skill.py`           | Scaffold new Agent Skill (agentskills.io)               |
| `init_copilot_asset.py`   | Scaffold Copilot-specific assets (instructions, agents) |
| `quick_validate_skill.py` | Validate skill structure                                |
| `package_skill.py`        | Package skill into distributable zip                    |

## Links

- Specification: `references/specification.md`
- Advanced Features: `references/advanced-features.md`
- SKILL.md Templates: `assets/skill-templates.md`
- Docs Ingestion: `references/docs-ingestion.md`
- Official spec: https://agentskills.io/specification
- Claude Code skills: https://code.claude.com/docs/en/skills


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/init_skill.py

```python
#!/usr/bin/env python3
"""Initialize Agent Skill per agentskills.io specification.

This script scaffolds a new Agent Skill that works with any skills-compatible
agent (Claude, GitHub Copilot, Cursor, etc.).

Usage:
    python init_skill.py <skill-name> [--skills-dir <path>]

Examples:
    python init_skill.py pdf-processing
    python init_skill.py pdf-processing --skills-dir .llm-code/skills
"""

from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path


# agentskills.io spec: lowercase alphanumeric + hyphens, no consecutive hyphens
_SKILL_NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")


def _script_dir() -> Path:
    return Path(__file__).resolve().parent


def _find_repo_root(start: Path) -> Path:
    """Walk up until we find a .git directory or reach filesystem root."""
    current = start.resolve()
    while current != current.parent:
        if (current / ".git").exists():
            return current
        current = current.parent
    # Fallback: 4 levels up from script location
    return _script_dir().parents[3]


def _ensure_parent_dir(path: Path) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)


def _write_file_if_missing(path: Path, content: str) -> None:
    if path.exists():
        raise FileExistsError(f"File already exists: {path}")
    _ensure_parent_dir(path)
    path.write_text(content, encoding="utf-8")


def _mkdir_if_missing(path: Path) -> None:
    if path.exists():
        raise FileExistsError(f"Path already exists: {path}")
    path.mkdir(parents=True, exist_ok=False)


def _title_from_kebab(name: str) -> str:
    return " ".join(part.capitalize() for part in name.split("-"))


def _validate_skill_name(name: str) -> None:
    """Validate skill name per agentskills.io specification."""
    if len(name) < 1 or len(name) > 64:
        raise ValueError("skill-name must be 1-64 characters")
    if not _SKILL_NAME_RE.fullmatch(name):
        raise ValueError(
            "skill-name must be lowercase a-z0-9 plus single hyphens "
            "(no --, no leading/trailing -)"
        )


def init_skill(skill_name: str, skills_root: Path) -> Path:
    """Create a new Agent Skill following agentskills.io specification.

    Args:
        skill_name: Skill identifier (lowercase, hyphens allowed)
        skills_root: Directory where skills are stored

    Returns:
        Path to created skill directory
    """
    _validate_skill_name(skill_name)

    skill_dir = skills_root / skill_name
    _mkdir_if_missing(skill_dir)

    skill_md = skill_dir / "SKILL.md"
    title = _title_from_kebab(skill_name)

    # Template follows agentskills.io specification
    # https://agentskills.io/specification
    content = (
        "---\n"
        f"name: {skill_name}\n"
        "description: \"[TODO] Describe what this skill does and when to use it. Include discovery keywords.\"\n"
        "---\n\n"
        f"# {title}\n\n"
        "## When to Use\n\n"
        "- [TODO] Situations and triggers\n\n"
        "## Quick Navigation\n\n"
        "- Topic A: `references/topic-a.md`\n\n"
        "## Steps / Recipes\n\n"
        "1. [TODO]\n\n"
        "## Critical Prohibitions\n\n"
        "- [TODO]\n\n"
        "## Links\n\n"
        "- [TODO] External references\n"
    )

    _write_file_if_missing(skill_md, content)

    # Create references directory per agentskills.io progressive disclosure pattern
    (skill_dir / "references").mkdir(exist_ok=True)

    # Create README.md for human readers
    readme_content = (
        f"# {title}\n\n"
        "[TODO] Brief description for human readers.\n\n"
        "## Quick Navigation\n\n"
        "- [SKILL.md](SKILL.md) — Entry point for agents\n"
        "- [references/](references/) — Detailed documentation\n"
    )
    readme_path = skill_dir / "README.md"
    if not readme_path.exists():
        readme_path.write_text(readme_content, encoding="utf-8")

    return skill_dir


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        prog="init_skill.py",
        description="Initialize Agent Skill per agentskills.io specification",
    )
    parser.add_argument(
        "skill_name",
        help="Skill identifier (lowercase, a-z0-9 and hyphens only)",
    )
    parser.add_argument(
        "--skills-dir",
        dest="skills_dir",
        default=None,
        help="Directory for skills (default: current directory)",
    )

    args = parser.parse_args(argv)

    # Determine skills directory
    if args.skills_dir:
        skills_root = Path(args.skills_dir)
        if not skills_root.is_absolute():
            skills_root = Path.cwd() / args.skills_dir
    else:
        # Default: current working directory
        skills_root = Path.cwd()

    try:
        created = init_skill(args.skill_name, skills_root)
        print(f"✅ Created skill: {created}")
        return 0
    except Exception as exc:
        print(f"❌ {exc}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main())

```

### scripts/quick_validate_skill.py

```python
#!/usr/bin/env python3
"""Quick validation for SKILL.md per agentskills.io specification.

This is a lightweight validator intended for fast local checks.
It does NOT replace project-level checks.

Validates per https://agentskills.io/specification:
- SKILL.md exists
- YAML frontmatter exists with required fields (name, description)
- name: 1-64 chars, lowercase a-z0-9-, no --, no leading/trailing -
- name matches directory name
- description: 1-1024 chars, non-empty
- description must not contain angle brackets

Usage:
    python quick_validate_skill.py <skill-directory>
"""

from __future__ import annotations

import re
import sys
from pathlib import Path


# agentskills.io spec: lowercase alphanumeric + hyphens, no consecutive hyphens
_NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")


def _extract_frontmatter(text: str) -> str:
    if not text.startswith("---\n"):
        raise ValueError("No YAML frontmatter found (expected starting '---')")

    end = text.find("\n---", 4)
    if end == -1:
        raise ValueError("Invalid YAML frontmatter (missing closing '---')")

    return text[4:end]


def validate_skill_dir(skill_dir: Path) -> None:
    skill_dir = skill_dir.resolve()

    if not skill_dir.exists():
        raise FileNotFoundError(f"Skill directory not found: {skill_dir}")

    if not skill_dir.is_dir():
        raise ValueError(f"Not a directory: {skill_dir}")

    skill_md = skill_dir / "SKILL.md"
    if not skill_md.exists():
        raise FileNotFoundError(f"SKILL.md not found: {skill_md}")

    content = skill_md.read_text(encoding="utf-8")
    frontmatter = _extract_frontmatter(content)

    name_match = re.search(r"^name:\s*(.+)\s*$", frontmatter, re.MULTILINE)
    if not name_match:
        raise ValueError("Missing 'name:' in YAML frontmatter")

    name = name_match.group(1).strip().strip('"').strip("'")

    # agentskills.io spec: 1-64 characters
    if len(name) < 1 or len(name) > 64:
        raise ValueError(f"name must be 1-64 characters (got {len(name)})")

    if not _NAME_RE.fullmatch(name):
        raise ValueError(
            "name must be lowercase a-z0-9 plus single hyphens (no --, no leading/trailing -)"
        )

    if name != skill_dir.name:
        raise ValueError(
            f"Frontmatter name '{name}' must match directory name '{skill_dir.name}'"
        )

    desc_match = re.search(r"^description:\s*(.+)\s*$", frontmatter, re.MULTILINE)
    if not desc_match:
        raise ValueError("Missing 'description:' in YAML frontmatter")

    description = desc_match.group(1).strip().strip('"').strip("'")

    # agentskills.io spec: 1-1024 characters
    if len(description) < 1:
        raise ValueError("description must not be empty")
    if len(description) > 1024:
        raise ValueError(f"description must be max 1024 characters (got {len(description)})")

    if "<" in description or ">" in description:
        raise ValueError("description must not contain angle brackets (< or >)")


def main(argv: list[str]) -> int:
    if len(argv) != 1:
        print(
            "Usage: python quick_validate_skill.py <skill-directory>",
            file=sys.stderr,
        )
        return 1

    try:
        validate_skill_dir(Path(argv[0]))
        print("✅ Skill is valid")
        return 0
    except Exception as exc:
        print(f"❌ {exc}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))

```

### references/specification.md

```markdown
# Agent Skills Specification

Source: https://agentskills.io/specification

## Overview

Agent Skills are a lightweight, open format for extending AI agent capabilities. A skill is a folder containing a `SKILL.md` file with metadata and instructions.

## SKILL.md File Format

The file MUST contain:

1. YAML frontmatter (between `---` markers)
2. Markdown body with instructions

```markdown
---
name: skill-name
description: What this skill does and when to use it.
---

# Skill Title

Instructions go here...
```

## Frontmatter Fields

### Required: `name`

- 1-64 characters
- Lowercase alphanumeric + hyphens only (`a-z`, `0-9`, `-`)
- No consecutive hyphens (`--`)
- No leading/trailing hyphens
- MUST match parent directory name

### Required: `description`

- 1-1024 characters
- Describes what the skill does AND when to use it
- Include keywords for agent discovery

### Optional: `license`

License name or reference to bundled file.

```yaml
license: Apache-2.0
license: Proprietary. LICENSE.txt has complete terms
```

### Optional: `compatibility`

Environment requirements (1-500 chars). Only include if skill has specific needs.

```yaml
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Designed for Claude Code (or similar products)
```

### Optional: `metadata`

Arbitrary key-value pairs for additional properties.

```yaml
metadata:
  author: example-org
  version: "1.0"
```

### Optional: `allowed-tools`

Space-delimited list of pre-approved tools (experimental).

```yaml
allowed-tools: Bash(git:*) Bash(jq:*) Read
```

## Markdown Body

No format restrictions. Write whatever helps agents perform the task.

Recommended sections:

- Step-by-step instructions
- Input/output examples
- Common edge cases

**Size guideline:** Keep under 500 lines. Split longer content into referenced files.

## Progressive Disclosure Model

Skills use three-phase loading to manage context:

1. **Discovery** — At startup, agent loads only `name` + `description` (~50-100 tokens per skill)
2. **Activation** — When task matches, agent reads full `SKILL.md`
3. **Execution** — Agent follows instructions, loads referenced files as needed

## Agent Integration

### Filesystem-based agents

Skills activate when agent reads the file:

```bash
cat /path/to/my-skill/SKILL.md
```

### Tool-based agents

Skills activate via custom tool implementation (developer-defined).

### Context Injection Format

For Claude models, recommended XML format:

```xml
<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDFs...</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
</available_skills>
```

## Validation Rules

1. Frontmatter must parse as valid YAML
2. `name` must match directory name
3. `name` must follow naming constraints
4. `description` must be non-empty
5. No angle brackets in description (`<` or `>`)

## Security Considerations

When skills include scripts:

- Sandbox execution environments
- Allowlist trusted skills only
- Confirm before dangerous operations
- Log all script executions

## Reference Implementation

The `skills-ref` library provides validation and prompt generation:

```bash
# Validate a skill
skills-ref validate <path>

# Generate available_skills XML
skills-ref to-prompt <path>...
```

```

### assets/skill-templates.md

```markdown
# Skill Templates

Ready-to-use templates for creating Agent Skills.

## SKILL.md Template

```markdown
---
name: <skill-name>
description: "[TODO] Describe what this skill does and when to use it. Include trigger keywords."
---

# <Skill Title>

## When to Use

- [TODO] Situations and triggers

## Quick Navigation

- Topic A: `references/topic-a.md`
- Topic B: `references/topic-b.md`

## Goal

[TODO] 1-3 sentences describing what this skill enables.

## Steps / Recipes

1. [TODO]

## Critical Prohibitions

- [TODO]

## Definition of Done

- [TODO]

## Links

- [TODO] External references
```

## SKILL.md Template (Router Style)

For skills with extensive reference material:

```markdown
---
name: <skill-name>
description: "[Purpose] + [Keywords for discovery]"
---

# <Skill Title> (Skill Router)

This file is intentionally short. Based on your situation, open the right note under `references/`.

## Start Here

- New to <topic>? Read: `references/concepts.md`
- Quick setup? Read: `references/quickstart.md`
- Integration? Read: `references/api.md`

## Choose by Situation

### Data Modeling

- What goes where? Read: `references/modeling.md`

### Operations

- Deployment: `references/deployment.md`
- Troubleshooting: `references/troubleshooting.md`

## Critical Prohibitions

- [Key prohibitions that apply broadly]

## Links

- Official docs: <URL>
```

## Reference Note Template

```markdown
# <Topic Title>

Source: <URL or "Internal">

## What This Covers

- 1-3 bullets summarizing scope

## Actionable Takeaways

- 5-15 practical bullets
- Focus on what helps build/operate/debug
- Include gotchas inline

## Examples

[Code examples if essential]

## Related

- `references/related-topic.md`
```

## README.md Template

Human-readable description (not for LLM):

```markdown
# <Skill Name>

Brief description of what this skill provides.

## What This Skill Covers

- Bullet list of capabilities
- Keep it scannable

## Quick Navigation

- [SKILL.md](SKILL.md) — Entry point for agents
- [references/](references/) — Detailed documentation

## When to Use

Activate this skill when [brief trigger description].
```

## Frontmatter Examples

### Minimal (Required Only)

```yaml
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---
```

### With Optional Fields

```yaml
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
license: Apache-2.0
compatibility: Requires pdfplumber, PyPDF2
metadata:
  author: example-org
  version: "1.0"
---
```

### With Allowed Tools

```yaml
---
name: git-workflow
description: Git branching, merging, and release workflows.
allowed-tools: Bash(git:*) Read Write
---
```

### With Context Fork (Subagent)

```yaml
---
name: deep-research
description: Research a topic thoroughly in isolated context.
context: fork
agent: Explore
allowed-tools: Read Grep Glob
---
```

### Manual-Only Skill

```yaml
---
name: deploy
description: Deploy application to production
disable-model-invocation: true
---
```

### Background Knowledge (Not User-Invocable)

```yaml
---
name: api-conventions
description: API design patterns for this codebase
user-invocable: false
---
```

### With Argument Hint

```yaml
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
argument-hint: <issue-number>
metadata:
  author: team
  version: "1.0.0"
---
```

### Full Example (All Fields)

```yaml
---
name: pr-review
description: Review pull request for issues. Use when asked to review PR or code changes.
license: MIT
compatibility: Requires gh CLI
context: fork
agent: Explore
disable-model-invocation: true
argument-hint: [pr-number]
allowed-tools: Read Grep Bash(gh:*)
metadata:
  author: example-org
  version: "1.0.0"
---
```

## Skill with Dynamic Context Template

```markdown
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task

Summarize this pull request focusing on:
1. Main changes
2. Potential issues
3. Testing recommendations
```

## Skill with Arguments Template

```markdown
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
argument-hint: <issue-number>
---

Fix GitHub issue $ARGUMENTS following our coding standards:

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit with message referencing the issue
```

## metadata.json Template

```json
{
  "version": "1.0.0",
  "organization": "Your Organization",
  "date": "January 2026",
  "abstract": "Comprehensive description of what this skill provides, its scope, and how it helps automated code generation and review.",
  "references": [
    "https://docs.example.com",
    "https://github.com/org/repo",
    "https://example.com/api-reference"
  ]
}
```

## Description Examples

### Good Descriptions

```yaml
# Includes purpose + triggers + keywords
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

description: Qdrant vector database playbook: core concepts (collections/points/payload), filtering, indexing, snapshots, deployment. Keywords: Qdrant, vector database, embeddings, ANN.

description: PostgreSQL RLS policies for multi-tenant applications. Use when implementing row-level security, tenant isolation, or app.current_user patterns.
```

### Poor Descriptions

```yaml
# Too vague
description: Helps with PDFs.

# Missing triggers
description: A skill for database operations.

# No keywords
description: Handles some common tasks.
```

## Naming Examples

### Valid Names

```
pdf-processing
data-analysis
code-review
qdrant
postgresql-rls
mcp-server
```

### Invalid Names

```
PDF-Processing    # uppercase
-pdf              # leading hyphen
pdf-              # trailing hyphen
pdf--processing   # consecutive hyphens
my skill          # spaces
my_skill          # underscores
```

```

### references/advanced-features.md

```markdown
# Advanced Skill Features

Extended features for Claude Code and other advanced agent environments.

## Context Forking (Subagents)

Run a skill in isolation with `context: fork`. The skill becomes the prompt for a subagent without conversation history.

```yaml
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
```

### Agent Types

| Agent | Best For |
|-------|----------|
| `Explore` | Research, code analysis, finding patterns |
| `Plan` | Creating implementation plans, breaking down tasks |

### When to Use Context Fork

- Tasks that benefit from fresh context
- Research that shouldn't pollute main conversation
- Long-running analysis that might exceed context limits
- Tasks where isolation prevents interference

## Allowed Tools

Restrict which tools a skill can use:

```yaml
---
name: safe-reader
description: Read files without making changes
allowed-tools: Read Grep Glob
---
```

### Common Tool Restrictions

| Use Case | Allowed Tools |
|----------|---------------|
| Read-only analysis | `Read Grep Glob` |
| Code review | `Read Grep Glob Write` |
| Git operations | `Bash(git:*)` |
| Python scripts | `Bash(python:*)` |

### Tool Syntax

- Simple: `Read Grep Glob`
- With patterns: `Bash(git:*) Bash(npm:*)`
- All bash: `Bash(*)`

## Invocation Control

### Manual-Only Skills

For workflows with side effects that users should control:

```yaml
---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. Run test suite
2. Build application
3. Push to deployment target
```

### Background Knowledge Skills

For reference material that shouldn't appear in `/` menu:

```yaml
---
name: api-conventions
description: API design patterns for this codebase
user-invocable: false
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
```

## Dynamic Context

Inject live data using `!`command`` syntax:

```yaml
---
name: pr-review
description: Review pull request with current data
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## Current PR State
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Review Task
Analyze this PR for issues...
```

### How It Works

1. Commands execute **before** the prompt is sent
2. Output replaces the `!`command`` placeholder
3. Agent receives fully-rendered content with real data

### Use Cases

- Fetching current git state
- Getting issue/PR details
- Reading dynamic configuration
- Gathering system information

## Argument Hints

Show users what arguments are expected:

```yaml
---
name: analyze-file
description: Analyze a specific file
argument-hint: <filename> [--verbose]
---
```

Appears in autocomplete as: `/analyze-file <filename> [--verbose]`

## Model Override

Force a specific model for a skill:

```yaml
---
name: complex-analysis
description: Deep analysis requiring advanced reasoning
model: claude-3-opus-20240229
---
```

## Extended Thinking

Include "ultrathink" anywhere in skill content to enable extended thinking mode.

## Hooks

Scope hooks to skill lifecycle:

```yaml
---
name: my-skill
hooks:
  on-invoke:
    - command: echo "Skill invoked"
  on-complete:
    - command: echo "Skill completed"
---
```

See agent documentation for full hooks configuration.

## Examples Structure

Include `examples/` folder for sample outputs:

```
my-skill/
├── SKILL.md
└── examples/
    ├── basic-output.md     # Simple example
    ├── complex-output.md   # Advanced example
    └── edge-case.md        # Handling edge cases
```

Reference in SKILL.md:
```markdown
See `examples/basic-output.md` for expected format.
```

```

### references/docs-ingestion.md

```markdown
# Docs Ingestion Workflow

Autonomous workflow for creating skills from external documentation.

## When to Use

- Building a skill from vendor docs (multiple pages)
- Entry links are section pages with many sub-pages
- Want agent to ingest sequentially without asking after each page
- Goal is a practical playbook, not a docs mirror

## Output Structure

```
<skill-name>/
├── SKILL.md           # High-signal entry point
├── plan.md            # Progress tracking (temporary)
└── references/
    ├── concepts.md
    ├── api.md
    └── ...
```

## Phase 1: Scaffold

1. Create skill folder
2. Create `SKILL.md` with skeleton frontmatter
3. Create `plan.md` using checkbox format
4. Create `references/` directory

The skill should be valid even before ingestion starts.

## Phase 2: Build Ingestion Queue

For each provided doc link:

**If section/landing page:**

1. Fetch the page
2. Extract internal doc links (skip navigation duplicates)
3. Add content pages to queue

**If single doc page:**

- Add directly to queue

### Queue Prioritization

Prefer order: concepts → API → operations → troubleshooting

Prioritize pages answering:

- Data model decisions
- Integration patterns
- Failure modes and recovery
- Production deployment notes

### Queue Rules

- De-duplicate URLs
- Skip non-content pages (nav, footer links)
- Limit to relevant documentation scope

## Phase 3: Ingest Loop

**Repeat until queue is empty:**

### Step 1: Fetch One Page

Use `ai_fetch_url` or similar tool.

### Step 2: Create Reference Note

Create `references/<topic>.md`:

```markdown
# <Page Title>

Source: <URL>

## What this page is about

- 1-3 bullets

## Actionable takeaways

- 5-15 bullets of practical guidance

## Gotchas / prohibitions

- 0-7 bullets

## How to apply in a real repo

- 3-6 bullets
```

### Step 3: Update plan.md

- Mark checkbox as completed
- Add new unchecked items if page reveals sub-topics

### Step 4: Update SKILL.md (Conditionally)

Only update if it improves the practical playbook:

- Add a recipe
- Add a checklist
- Add an explicit rule of thumb

**Do NOT ask user after each page** — continue autonomously.

## Phase 4: Finalize

When queue is empty:

1. Review `SKILL.md` for:

   - Minimal mental model
   - Practical recipes
   - Ops runbook/checklists
   - Clear definition of done

2. Verify `plan.md` reflects what was ingested

3. Check file naming is consistent

**Note:** `plan.md` may be deleted manually after ingestion. Agent must NOT delete it automatically.

## Quality Gate

### Do

- Summarize in your own words
- Focus on what helps build/operate/debug
- Include practical examples
- Keep `SKILL.md` as router to references

### Do NOT

- Replicate documentation structure just because it exists
- Keep long code samples unless essential
- Introduce project-specific paths or secrets
- Create verbatim docs mirrors

## Plan Template

```markdown
# <Skill Name> Plan

Progress tracking for docs ingestion.

## Queue

- [ ] Initial seed links
- [ ] Expand section pages

## Foundation

- [ ] Concepts / mental model
- [ ] Installation / quickstart
- [ ] Data model

## Integration

- [ ] SDK/client usage
- [ ] Authentication
- [ ] Error handling

## Operations

- [ ] Deployment
- [ ] Monitoring
- [ ] Troubleshooting
```

## Reference Note Template

```markdown
# <Page Title>

Source: <URL>

## What this page is about

- <1-3 bullets>

## Actionable takeaways

- <5-15 bullets>

## Gotchas / prohibitions

- <0-7 bullets>

## How to apply in a real repo

- <3-6 bullets>
```

```