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)

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:

---
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

Optional Fields (Top Level)

metadata Object (Common Fields)

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)

Invocation Control Matrix

Variable Substitutions

Available placeholders in skill content:

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

Example:

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

## 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:

{
  "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

# 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:

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:

# 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

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

---
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

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:

## 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:

---
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

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