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:

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

Example:

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

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) 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 Step 1: Scaffold python scripts/init_skill.py

Or specify custom directory:

python scripts/init_skill.py --skills-dir skills

Or manually create:

// ├── SKILL.md ├── references/ # For documentation, guides └── assets/ # For templates, static files

Step 2: Write Frontmatter

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/.md with:

Actionable takeaways (5-15 bullets) Gotchas / prohibitions Practical examples Step 5: Add Assets (if needed)

For templates or static resources, create assets/:

Document templates Configuration templates Schema files Step 6: Validate python scripts/quick_validate_skill.py

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

When creating or updating a skill from external documentation:

Add version field in frontmatter for product version:

Optionally add release_date if known:

Create README.md with:

Skill overview (1-2 sentences) Usage section (when to use) Links section (standardized format)

README.md Links section format:

Links

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

skill-master

安装