vt-c-create-agent-skills

Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.

Plugin: core-standards
Category: Tooling
Command: /vt-c-create-agent-skills

---

How Skills Work

Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills.

1. Skills Are Prompts

All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.

2. SKILL.md Is Always Loaded

When a skill is invoked, Claude reads SKILL.md. Use this guarantee: - Essential principles go in SKILL.md (can't be skipped) - Workflow-specific content goes in workflows/ - Reusable knowledge goes in references/

3. Router Pattern for Complex Skills

skill-name/
├── SKILL.md              # Router + principles
├── workflows/            # Step-by-step procedures (FOLLOW)
├── references/           # Domain knowledge (READ)
├── templates/            # Output structures (COPY + FILL)
└── scripts/              # Reusable code (EXECUTE)

SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read.

When to use each folder: - workflows/ - Multi-step procedures Claude follows - references/ - Domain knowledge Claude reads for context - templates/ - Consistent output structures Claude copies and fills (plans, specs, configs) - scripts/ - Executable code Claude runs as-is (deploy, setup, API calls)

4. Pure XML Structure

No markdown headings (#, ##, ###) in skill body. Use semantic XML tags:

<objective>...</objective>
<process>...</process>
<success_criteria>...</success_criteria>

Keep markdown formatting within content (bold, lists, code blocks).

5. Progressive Disclosure

SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow.

What would you like to do?

1. Create new skill
2. Audit/modify existing skill
3. Add component (workflow/reference/template/script)
4. Get guidance

Wait for response before proceeding.

| Response | Next Action | Workflow | |----------|-------------|----------| | 1, "create", "new", "build" | Ask: "Task-execution skill or domain expertise skill?" | Route to appropriate create workflow | | 2, "audit", "modify", "existing" | Ask: "Path to skill?" | Route to appropriate workflow | | 3, "add", "component" | Ask: "Add what? (workflow/reference/template/script)" | workflows/add-{type}.md | | 4, "guidance", "help" | General guidance | workflows/get-guidance.md |

Progressive disclosure for option 1 (create): - If user selects "Task-execution skill" → workflows/create-new-skill.md - If user selects "Domain expertise skill" → workflows/create-domain-expertise-skill.md

Progressive disclosure for option 3 (add component): - If user specifies workflow → workflows/add-workflow.md - If user specifies reference → workflows/add-reference.md - If user specifies template → workflows/add-template.md - If user specifies script → workflows/add-script.md

Intent-based routing (if user provides clear intent without selecting menu): - "audit this skill", "check skill", "review" → workflows/audit-skill.md - "verify content", "check if current" → workflows/verify-skill.md - "create domain expertise", "exhaustive knowledge base" → workflows/create-domain-expertise-skill.md - "create skill for X", "build new skill" → workflows/create-new-skill.md - "add workflow", "add reference", etc. → workflows/add-{type}.md - "upgrade to router" → workflows/upgrade-to-router.md

After reading the workflow, follow it exactly.

Skill Structure Quick Reference

Simple skill (single file):

---
name: vt-c-create-agent-skills
description: What it does and when to use it.
---

<objective>What this skill does</objective>
<quick_start>Immediate actionable guidance</quick_start>
<process>Step-by-step procedure</process>
<success_criteria>How to know it worked</success_criteria>

Complex skill (router pattern):

SKILL.md:
  <essential_principles> - Always applies
  <intake> - Question to ask
  <routing> - Maps answers to workflows

workflows/:
  <required_reading> - Which refs to load
  <process> - Steps
  <success_criteria> - Done when...

references/:
  Domain knowledge, patterns, examples

templates/:
  Output structures Claude copies and fills
  (plans, specs, configs, documents)

scripts/:
  Executable code Claude runs as-is
  (deploy, setup, API calls, data processing)

Architecture Patterns

• Compact constraints (for agents): references/architecture-constraints.md — actionable rules loaded via workflow required_reading
• Full reference (for humans): plugins/core-standards/docs/agent-architecture-patterns.md — conceptual explanations, diagrams, toolkit examples

Domain Knowledge

All in references/:

Structure: recommended-structure.md, skill-structure.md Principles: core-principles.md, be-clear-and-direct.md, use-xml-tags.md Patterns: common-patterns.md, workflows-and-validation.md Assets: using-templates.md, using-scripts.md Advanced: executable-code.md, api-security.md, iteration-and-testing.md Cache: cache-lifecycle.md — compaction, forking, and model switching cache behavior. Essential reading for orchestrator and long-session agent authors. Agents: agent-frontmatter-fields.md — all agent YAML frontmatter fields including the isolation decision checklist. Essential reading when creating or auditing agents. Architecture: architecture-constraints.md — CC 2.1 architecture rules (fork, hooks, permissions, orchestrators). Loaded by create/audit workflows via required_reading. Intent Engineering: intent-engineering-checklist.md — audit rubric for boundary statements, task completion definitions, constraint enumeration, and failure mode flagging. Essential reading when creating or auditing high-autonomy agents and fork-context skills.

Workflows

All in workflows/:

Workflow	Purpose
create-new-skill.md	Build a skill from scratch
create-domain-expertise-skill.md	Build exhaustive domain knowledge base for build/
audit-skill.md	Analyze skill against best practices
verify-skill.md	Check if content is still accurate
add-workflow.md	Add a workflow to existing skill
add-reference.md	Add a reference to existing skill
add-template.md	Add a template to existing skill
add-script.md	Add a script to existing skill
upgrade-to-router.md	Convert simple skill to router pattern
get-guidance.md	Help decide what kind of skill to build

YAML Frontmatter

Required fields:

---
name: vt-c-create-agent-skills
description: ...          # What it does AND when to use it (third person)
---

Name conventions: create-*, manage-*, setup-*, generate-*, build-*

A well-structured skill: - Has valid YAML frontmatter - Uses pure XML structure (no markdown headings in body) - Has essential principles inline in SKILL.md - Routes directly to appropriate workflows based on user intent - Keeps SKILL.md under 500 lines - Asks minimal clarifying questions only when truly needed - Has been tested with real usage