Create Agent Skills

Environment Preflight (Required for Bash Commands)

Before running any command that uses ${AGENT_ROOT}, initialize the shell:

source ./scripts/agent-env.sh

This sets AGENT_ROOT to ./.agents for the current working directory.

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 the assistant is smart - only add context the assistant doesn't have.

2. SKILL.md Is Always Loaded

When a skill is invoked, the assistant 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 the assistant follows
• references/ - Domain knowledge the assistant reads for context
• templates/ - Consistent output structures the assistant copies and fills (plans, specs, configs)
• scripts/ - Executable code the assistant 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.

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

Wait for response before proceeding.

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.

Simple skill (single file):

---
name: skill-name
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 the assistant copies and fills
  (plans, specs, configs, documents)

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

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

All in workflows/:

Required fields:

---
name: skill-name          # lowercase-with-hyphens, matches directory
description: ...          # What it does AND when to use it (third person)
---

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