itechmeat/llm-code/skill-master

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.

Links

• Agent Skills Specification
• What are Skills?
• Integrate Skills
• The Complete Guide to Building Skills for Claude (Anthropic)

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)

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

Optional Fields (Top Level)

metadata Object (Common Fields)

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.

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)

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

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