Skill Master

Create, edit, and validate Agent Skills following the open agentskills.io specification. 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
Writing effective descriptions & instructions? Read: references/writing-skills.md
Structuring multi-step processes? Read: references/workflows.md
Adding scripts to a skill? Read: references/scripts.md
Adding assets/templates to a skill? Read: references/assets.md
Advanced features (context, agents, hooks)? Read: references/advanced-features.md
Creating from docs? Read: references/docs-ingestion.md
Testing, evals, benchmarking, or iterative improvement? Read: references/testing-troubleshooting.md, references/eval-testing.md, references/iterative-improvement.md
Description optimization? Read: references/description-optimization.md
JSON schemas (evals, grading, benchmark)? Read: references/schemas.md
Eval set review UI and output viewer? See: assets/eval_review.html, eval-viewer/
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
Running the full skill-creator-style loop: interview, draft, eval, benchmark, viewer review, and iteration

skill-master subsumes skill-creator; for the detailed operator playbook, workspace layout, timing capture, benchmark analysis, and viewer handoff, read references/iterative-improvement.md.

Skill Structure (Required)

my-skill/
├── SKILL.md          # Required: instructions + metadata (must be human-readable too)
├── 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

Do NOT include README.md in skill folders. SKILL.md is the single source of truth. If migrating a skill with README.md, merge its content into SKILL.md and delete it.

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

references/ — documentation the agent reads and understands
examples/ — sample outputs showing expected format
assets/ — templates, configs, schemas to copy verbatim
scripts/ — executable code the agent runs

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.2.3"
  release_date: "2026-01-01"
---

Field order: name → description → license → compatibility → metadata

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	Upstream product version or skill version
release_date	Last meaningful update date (`YYYY-MM-DD`)
argument-hint	Hint for autocomplete, e.g., `[issue-number]`

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:

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

Formulas:

For library/reference skills (Claude Code, keyword-based discovery):

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

For workflow/automation skills (Claude.ai, trigger-based activation):

[What it does]. Use when user [specific trigger phrases].

Critical for auto-triggering: include explicit "Use when user says / asks / mentions..." phrases. Without them, Claude may not load the skill automatically. See references/writing-skills.md for good/bad examples and debugging tips.

Constraints:

Target: 80-150 chars
Max: 1024 chars (300 if keeping it minimal)
No marketing ("powerful", "comprehensive", "modern")
No filler ("this skill", "use this for", "helps with")
No XML angle brackets < >
Names with "claude" or "anthropic" are reserved

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)

Discovery: Agent loads only name + description of each skill (~50-100 tokens)
Activation: When task matches, agent reads full SKILL.md into context
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

Pro Tip: You can use the skill-creator skill (available in Claude.ai or Claude Code) to interactively generate your first draft, then refine it using the steps below.

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 Scripts (if applicable)

Consult references/scripts.md for when scripts are worth writing and how to structure them.

Language selection:

Python — default for CLI wrappers, validators, scaffolding
Go — when the skill's ecosystem is Kubernetes/cloud-native (see k8s-cluster-api)
JS/TS — when the skill's ecosystem is Node/npm

Minimal checklist for a script:

argparse (Python) or flag (Go) for all parameters — no hardcoded values
Check tool availability before use (shutil.which() in Python)
Docstring at top with Usage + Examples
All exceptions caught; exit non-zero with a message to stderr

Step 6: Add Assets (if needed)

Consult references/assets.md for when assets are worth creating and how to format them.

For templates or static resources, create assets/<resource>. Common types:

Config templates — .minimal.yaml / .full.yaml pair; add # yaml-language-server: $schema= header
YAML manifests — use ${VAR_NAME:=default} for variables; include purpose + usage comment at top
Text templates — use #-prefixed comments to explain fields and valid values
Markdown checklists / runbooks — - [ ] checkboxes, inline commands, sign-off section
Prompt / prose templates — grouped by use case, each block self-contained

Naming: <tool>.minimal.yaml, <purpose>-checklist.md, <name>.template, <topic>-prompts.md.

Step 7: Validate

python scripts/quick_validate_skill.py <skill-path>
# Compatibility alias:
python scripts/quick_validate.py <skill-path>

Creating a Skill from Documentation

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

Phase 1: Scaffold

Create skill folder with SKILL.md skeleton
Create plan.md for progress tracking
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:

Fetch one page
Create references/<topic>.md with actionable summary
Update plan.md checkbox
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

What `version` Means

In this repository, store version metadata as metadata.version and metadata.release_date to match the existing skills and current Copilot skill-file validation. metadata.version holds the upstream product version the skill was built against (e.g., "1.12.3" for CAPI v1.12.3). For standalone skills not tied to an external product, it holds the skill's own version (e.g., "1.2.4" for skill-master). Use "—" when the product uses continuous deployment with no semantic versioning (e.g., hosted services like Cloudflare Workers).

When to Update

Trigger	Update `metadata.version`	Update `metadata.release_date`
Product released a new version	✅ Yes	✅ Yes
Content changed, no upstream version	❌ No	✅ Yes
Typo or minor fix	❌ No	❌ No

When bumping metadata.version or making significant content changes, also update:

SKILLS_VERSIONS.md — set new version + date, move row to top of table
CHANGELOG.md — prepend a new dated block at the top

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

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

Validation Checklist

Pro Tip: You can use the skill-creator skill (available in Claude.ai or Claude Code) to review your skill and suggest improvements before finalizing.

name matches folder name, kebab-case, 1-64 chars, no --
description includes WHAT it does AND WHEN to use it (trigger phrases)
description has no XML angle brackets < >
SKILL.md under 500 lines
Documentation in references/, templates in assets/
Complex multi-step processes extracted to references/workflows.md
All text in English
Skill triggers on obvious test queries
Skill does NOT trigger on unrelated queries

Full pre-publish checklist: references/testing-troubleshooting.md

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
`quick_validate.py`	Compatibility wrapper for legacy validation workflow
`package_skill.py`	Package skill into distributable zip
`run_eval.py`	Run evals via `claude -p` with parallel workers
`run_loop.py`	Eval+improve loop with train/test split
`improve_description.py`	Improve skill description using eval feedback
`aggregate_benchmark.py`	Aggregate grading results into benchmark stats
`generate_report.py`	Generate HTML report from loop iteration data

Agents: agents/grader.md (grade expectations), agents/comparator.md (blind A/B comparison), agents/analyzer.md (post-hoc analysis + benchmark)