ahundt/ai-skill-builder

AI Skill Builder

Build Agent Skills using the shared SKILL.md format and Anthropic's methodology: the smallest portable core that works in every named target, plus explicit runtime adapters. Portability is a tested compatibility claim, not a formatting style. references/sources.md cites host documentation for Claude Code, Codex, and Qwen Code; every other host is untested here, so verify the one you target (Step 1).

This methodology deliberately requires consistent semantic XML regions inside the Markdown body. That is a quality policy for reducing ambiguity in complex operational instructions, supported by current Anthropic prompting guidance and checked by the forward tests in Step 4. It is not a parser requirement of the portable Agent Skills specification, an authorization boundary, or a claim that XML alone prevents prompt injection.

Primary methodology source: "The Complete Guide to Building Skills for Claude" (Anthropic, January 2026)

• PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Extracted text: references/ai-skill-builder-guide.md

Portable format source: https://agentskills.io/specification

---

Quick Start

To create a skill from scratch, follow the 4-phase process below. To improve an existing skill, read references/refining-skills.md. To validate structure, run scripts/audit-skill.sh.

Invoke with: ask for ai-skill-builder; hosts may expose it as /ai-skill-builder, $ai-skill-builder, or through their skills picker.

P0 requirements

Every skill this methodology produces meets all thirteen. Cite them by ID in audits and reviews.

1. SKILL-REQ001-discover-target-runtimes. Identify exact products, versions, invocation modes, install roots, trust boundaries, and filesystem semantics before authoring.
2. SKILL-REQ002-separate-standard-from-extensions. Keep the Agent Skills specification, runtime extensions, and project conventions in separate columns. Never present a Claude-, Codex-, Copilot-, Gemini-, or framework-specific field as universal.
3. SKILL-REQ003-use-valid-portable-core. Put a required SKILL.md in a directory whose name matches its portable name; include a specific description that says what the skill does and when to use it. Use standard optional fields only when needed.
4. SKILL-REQ004-use-semantic-xml-regions. Wrap every major operational region in consistent, descriptive XML tags inside the Markdown body, such as <purpose>, <requirements>, <workflow>, <examples>, and <output_contract>. Keep Markdown inside those regions and literal source in fenced code blocks. This mandatory methodology rule aims for the highest-quality instruction separation; it is not an Agent Skills parser requirement or a security boundary. scripts/audit-skill.sh fails a body with no region, an unbalanced or mis-nested tag, or a ## heading outside every region.
5. SKILL-REQ005-design-progressive-disclosure. Keep the activation description precise and the main workflow concise. Move genuinely conditional detail into focused, directly linked references; keep reusable automation in scripts and output materials in assets.
6. SKILL-REQ006-preserve-operational-context. Every reference or script must say when to use it, what inputs it accepts, what it returns or changes, and how failure is reported. Avoid deep reference chains.
7. SKILL-REQ007-make-invocation-correct. Test automatic activation and explicit invocation. Where a runtime supports parameters, test empty, positional, named, quoted, Unicode, invalid, and large inputs. Do not assume another runtime implements the same substitution syntax.
8. SKILL-REQ008-minimize-tool-authority. Treat skills and bundled scripts as executable dependencies. Request the least authority needed, validate inputs, preserve approval prompts where practical, and never describe prompt delimiters as prompt-injection prevention.
9. SKILL-REQ009-validate-every-harness. Validate discovery, load, references, scripts, arguments, symlinks, duplicate resolution, updates, and removal in each supported harness. Passing one parser does not prove cross-runtime compatibility.
10. SKILL-REQ010-preserve-user-state. Installation and uninstall must own exact generated paths, preserve manual edits, support multiple configured skill roots, and remove only installer-owned links or files.
11. SKILL-REQ011-measure-context-and-runtime-cost. Record discovery metadata size, loaded instruction size, conditional reference cost, script time/memory/I/O, and duplicate loading. Treat line and token targets as heuristics unless a target runtime makes them normative.
12. SKILL-REQ012-forward-test-real-tasks. Use realistic positive, negative, ambiguous, and adversarial prompts. Check task outcome, not merely whether the skill appeared in a list.
13. SKILL-REQ013-separate-authoring-from-execution. Classify whether the task is to change the skill, use the skill to produce an artifact or result, or evaluate the skill from evidence. Runtime inputs, generated outputs, examples, and dogfood observations do not become skill instructions unless an explicit authoring decision accepts and generalizes them.

Region names follow the task rather than one universal taxonomy: workflows use <workflow>, reference skills may use <decision_guide>, multi-mode skills <routing>, strict result contracts <output_contract>, inline reference material <reference>, and pointers to bundled files and sources <resources>. Tags must be consistent, descriptive, balanced, and no more deeply nested than the task requires. The standard-versus-extension matrix, the claim audit, and the per-host validation receipt live in references/portability-and-claim-audit.md.

How It Works

Four-phase methodology from the Anthropic guide. Each phase carries a Definition of Done: the condition that must hold before the next phase starts.

Phase	Activity	Definition of Done
1: Planning & Design	Define target hosts, use cases, category, success criteria	Criteria are measurable and the category is chosen
2: Implementation	Create folder, write SKILL.md, add resources	audit-skill.sh reports no failures
3: Testing	Triggering, functional, performance, compatibility, forward tests	Every named host passes with a validation receipt; baseline recorded
4: Distribution	Package, document, publish	Install verified from a clean root

Phase 1 covers Steps 1–2 below; Phases 2–4 correspond to Steps 3–5.

How long a phase takes depends on who or what runs it, so this skill states no wall-clock estimates and the skills you build should not either.

---

Skill Creation Workflow

Step 1: Discover Requirements

Research the domain first — use the host's web tools to verify current best practices before writing instructions. Outdated guidance is worse than none: an agent follows it confidently.

Retain all sources: record every URL consulted with a note of what it confirmed. Unsourced guidance cannot be verified or updated.

For research strategies, source quality standards, and the required Sources section format: references/research.md

1. Classify the request: authoring (change the skill), execution (use the skill to produce a result), or evaluation (judge the skill from evidence). Name the artifact and the mutation boundary before using task content as design input (SKILL-REQ013).
2. Identify the problem and target users
3. Identify every target host and version, its discovery root, invocation form, and reload behavior. Mark unknowns as unknown rather than guessing. Inspect existing skill roots and project guidance before creating a parallel package.
4. Define 2-3 concrete use cases
5. Set measurable success criteria (time saved, errors reduced, quality improved)
6. Choose a skill category:

Category	INPUT → OUTPUT	Examples
1: Document & Asset Creation	Data/specs → document, code, report	API test generator, meeting notes summarizer
2: Workflow Automation	Task params → completed multi-step process	Deploy pipeline, code review workflow
3: MCP Enhancement	MCP tool outputs → smarter orchestration	Smart file search, BigQuery assistant

For in-depth category guidance: references/categories.md For interactive discovery questions: references/discovery.md

Step 2: Design Structure

Design using progressive disclosure — 3 loading levels:

Level	When loaded	Target length	Content
1: Metadata	Always (~100 words)	name + description	Trigger conditions
2: SKILL.md body	When skill triggers	under 5,000 words (ideally under 2,000)	Core workflow + pointers
3: references/ files	As needed	Unlimited	Deep detail, schemas, examples

For progressive disclosure writing tips and success metrics: references/best-practices.md

Step 3: Implement

Critical Rules:

• ✅ File MUST be named SKILL.md (not README.md)
• ✅ Folder name MUST be kebab-case — no spaces, no capitals (my-skill not My Skill)
• ✅ YAML frontmatter MUST include name and description; put a version under metadata
• ✅ Description MUST include specific trigger phrases — what users SAY to activate the skill
• ✅ Description must be under 1024 characters (hard limit — longer descriptions are truncated)
• ✅ No XML angle brackets (< or >) in any frontmatter field — a host restriction from Anthropic's skill guide, not a YAML rule; the body is unaffected
• ✅ Body: every major section sits inside a balanced, descriptive XML region on its own line (<purpose>, <requirements>, <workflow>, <examples>, <output_contract>), Markdown inside, literal source in fenced code blocks (SKILL-REQ004). The H1 title may stay outside.
• ❌ NO README.md inside the skill folder — all docs go in SKILL.md or references/ (Exception: a README.md at the GitHub repo ROOT, outside the skill folder, is fine for GitHub.)
• ❌ NO spaces or underscores in folder names (my_skill → my-skill)

Frontmatter: required fields:

---
name: your-skill-name          # kebab-case only; no spaces, capitals, or underscores
description: What it does. Use when user asks to "specific phrase", "another phrase".
             # MUST include: what it does + when to use it (trigger conditions)
             # Under 1024 characters. No XML angle brackets.
             # Do NOT start with "claude" or "anthropic" (reserved namespaces).
---

For every optional field (license, compatibility, allowed-tools, metadata) with host-portability notes: references/best-practices.md

Positioning language ("generate tests 87% faster") belongs in the repo README, never in description. See references/best-practices.md.

Folder structure (annotated Claude Code standalone example: references/best-practices.md, section "Folder Structure Patterns"):

Directory	Load into context?	Use for
references/	Yes, as needed	Schemas, API docs, policies, workflow guides
references/examples/	As needed	Working code users copy and adapt
scripts/	No (run directly)	Validators, scaffolders, utilities
assets/	No (used in output)	Images, fonts, HTML templates the skill pastes into output

Note: Plugin skills (in plugin-name/skills/) may place examples/ at the top level — that is plugin-dev convention. For standalone ~/.claude/skills/ skills, put examples inside references/.

To scaffold a new skill: bash scripts/scaffold-skill.sh my-skill-name (set SKILLS_DIR to target another host's root) To start from template: copy references/examples/SKILL-template.md

Step 4: Test

Five testing approaches (run in order):

1. Triggering tests — verify the agent activates on expected phrases and not on unrelated requests
2. Functional tests — validate the skill's core workflow produces correct output for known inputs
3. Performance tests — measure improvement over baseline (time saved, error reduction, consistency)
4. Compatibility tests — verify discovery, explicit invocation, reference loading, script execution, and duplicate/name resolution on every named host and version. Start a clean session for each host, run the host's own validator where one exists (Codex ships skill-creator/scripts/quick_validate.py), test installer reruns, multiple roots, symlink targets, modified user files, and uninstall, and record a validation receipt per host (references/portability-and-claim-audit.md).
5. Forward tests — realistic positive, negative, ambiguous, and adversarial prompts; judge the task outcome, not whether the skill appeared in a list, and check that it does not over-trigger nearby tasks (SKILL-REQ012)

Debugging trigger issues:

Ask the agent: "When would you use the [skill name] skill?"

The agent should quote its description back. Adjust based on what's missing or too vague.

Fixing undertriggering: Add more specific trigger phrases and relevant technical terms.

Fixing overtriggering: Add negative triggers to the description:

description: Processes PDF legal documents for contract review. Use for "review this contract",
  "analyze legal document", "extract contract clauses". Do NOT use for general PDF viewing,
  image extraction, or non-legal documents (use doc-converter skill instead).

For the full diagnosis-and-fix guide covering all four failure modes: references/troubleshooting.md

To validate structure:

bash scripts/audit-skill.sh /path/to/YOUR-SKILL

For automated quality review on a host that provides Anthropic's skill-creator skill:

"Use the skill-creator skill to review the skill I just built and suggest improvements"

Claude Code with the plugin-dev plugin installed also offers a skill-reviewer agent that checks description quality.

For detailed test case templates and the Testing Triangle methodology: references/testing.md

Step 5: Distribute

Three channels — individual install into a host's skills root, organization-wide deployment, and the Messages API — are described with commands in references/distribution.md, together with the GitHub repo layout, the README template, versioning, and community channels.

An installer that places the skill must own exact generated paths, preserve manual edits, support multiple configured skill roots, and remove only its own links or files (SKILL-REQ010). Report the portable core and every runtime extension, the compatibility matrix and its evidence status, install/update/uninstall ownership, validation and forward-test results, and context/runtime costs. Do not claim "universal," "secure," or "supported" without a named contract and direct evidence.

Common Pitfalls

Pitfall	❌ Wrong	✅ Correct
File naming	my_skill/README.md	my-skill/SKILL.md
Description field	Outcome-focused: "generates tests 87% faster"	Trigger phrases: "create a skill", "improve my skill"
README positioning	Trigger phrases in GitHub README	Outcome-focused: "generate tests 87% faster"
No progressive disclosure	Monolithic wall of text	3-level: hook (50-100w) → workflow (200-400w) → detail
No testing	Write → publish immediately	Triggering + functional + performance + compatibility + forward tests
Missing success criteria	"Build a skill that helps with APIs"	"Cut API test writing from 3 h to 45 min, median of 3 runs"
Feature-focused description	"Uses OpenAPI parser and Jinja2 templates"	Trigger phrases + concise capability summary
Unmeasured claim	"Works with any agent host", a bare "40% faster"	The hosts and versions you tested; the workload, baseline, and unit behind the number. The 87% in the rows above is correct placement only if it was measured

---

Refining Existing Skills

Signs a skill needs refinement:

• File named README.md or folder has underscores/capitals (P0 — Claude cannot find it)
• Missing YAML frontmatter (P0 — Claude cannot auto-activate it)
• Description is outcome-focused instead of trigger-phrase format (P1)
• SKILL.md is over 5,000 words (P0 on Claude hosts, where Anthropic's guide reports degraded quality above it; a heuristic elsewhere, per SKILL-REQ011)
• SKILL.md is over 2,000 words with no references/ files (P1 — detail belongs in references/)
• Wall of text with no progressive disclosure structure (P1)
• No semantic XML regions, an unbalanced tag, or a ## heading outside every region (P1 — scripts/audit-skill.sh fails it; see SKILL-REQ004)

For the 5-step refinement process (audit → prioritize → fix → validate → document), migration scenarios, and before/after examples: references/refining-skills.md

Additional Resources

Reference Files (loaded as needed by the agent — when to open it → what it gives back)

• references/research.md — before writing any domain instruction → source-tier judgement, sources.md entries
• references/discovery.md — when requirements are unclear → 22-question plan: name, triggers, use cases, inputs, outputs, tests
• references/categories.md — when Step 1's category is not obvious → category, structure, Level 2 template
• references/best-practices.md — while writing body and frontmatter → description format, every optional field, level targets, 6 anti-patterns
• references/patterns.md — when 4 phases are not enough → orchestration, multi-MCP, refinement loops, runtime branching, domain rules
• references/testing.md — at Step 4 → T1-T6 triggering cases, F1-F4 functional cases, baseline comparison, per-host compatibility steps, forward-test kinds
• references/troubleshooting.md — when a built skill misbehaves → fixes for no trigger, over-trigger, skipped instructions, context overload
• references/refining-skills.md — when improving an existing skill → P0-P3 audit, migration checklist
• references/distribution.md — at Step 5 → distribution channels, repo layout, README, versioning
• references/portability-and-claim-audit.md — when a skill targets more than one host, or a claim about frontmatter, XML, roots, symlinks, or security needs checking → standard-vs-extension matrix, claim audit table, per-host validation receipt
• references/sources.md — when checking what a claim rests on, or adding one → citations, and claims with no retrievable source
• references/changelog.md — when changing ai-skill-builder itself → its release history, not the history of the skill you are building

Superseded package

• engineer-agent-skills — an earlier standalone skill. Its P0 requirements (SKILL-REQ001–013), portable-standard vs runtime-extension claim matrix, per-host validation receipt, and install/uninstall ownership rules now live in this skill; do not install both.

Scripts (run directly — do not load into context)

• scripts/audit-skill.sh — structure smoke test. Gate on zero FAILs; the percentage scores only the mechanically decidable checks, and proxy checks are listed unscored.

  bash scripts/audit-skill.sh /path/to/YOUR-SKILL
  

• scripts/scaffold-skill.sh — create a skill directory that already passes the audit

  SKILLS_DIR=~/.claude/skills bash scripts/scaffold-skill.sh my-skill-name