developing-skills

Progressive disclosure for option 1 (develop):

• If user selects "Task-execution skill" → workflows/develop-new-skill.md
• If user selects "Domain expertise skill" → workflows/develop-domain-expertise-skill.md

Progressive disclosure for option 3 (add component):

• If user specifies workflow → workflows/add-workflow.md
• If user specifies knowledge → workflows/add-knowledge.md
• If user specifies template → workflows/add-template.md
• If user specifies script → workflows/add-script.md

Intent-based routing (route immediately when the user provides clear intent):

• "audit this skill", "check skill", "review" → workflows/audit-skill.md
• "verify content", "check if current" → workflows/verify-skill.md
• "develop domain expertise", "exhaustive knowledge base" → workflows/develop-domain-expertise-skill.md
• "develop skill for X", "build new skill", "create skill" → workflows/develop-new-skill.md
• "run evals", "benchmark this skill", "test this skill", "measure performance" → workflows/evaluate-skill.md
• "optimize description", "improve triggering", "does this trigger correctly" → workflows/optimize-description.md
• "add workflow", "add knowledge", etc. → workflows/add-{type}.md
• "upgrade to router" → workflows/upgrade-to-router.md

After reading the workflow, follow it exactly.

<escalation_triggers> Stop and ask the user when:

• Skill scope is unclear after initial questions (don't guess at requirements)
• Multiple valid architectural approaches exist (simple vs. router pattern)
• External API is involved but documentation is outdated or conflicting
• Existing skill has unusual structure that may be intentional
• Changes would affect more than 10 files in an existing skill </escalation_triggers>

<quick_reference> 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 knowledge files to load
  <process> - Steps
  <success_criteria> - Done when...

knowledge/:
  Compiled domain knowledge, patterns, examples

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

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

</quick_reference>

<formatting_standard> Use XML tags for semantic structure in generated SKILL.md bodies. Do not use Markdown headings as the primary section structure of a skill body.

Workflow and knowledge files may use a single title heading and Markdown subheadings inside XML sections when they improve scanning, but every major section still needs XML boundaries such as <required_reading>, <process>, and <success_criteria>. Markdown headings inside fenced examples are always allowed. </formatting_standard>

<knowledge_index> All in knowledge/:

Structure: recommended-structure.md, skill-structure.md Principles: core-principles.md, llm-wiki-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; templates/ contains eval and report templates Quality: skill-checklist.md, evaluation-driven-development.md, iteration-and-testing.md Advanced: executable-code.md, api-security.md </knowledge_index>

<workflows_index> All in workflows/:

</workflows_index>

<evaluation_index> Skill-specific evals in evals/:

• behavior.json - realistic workflow behavior checks for this skill
• triggers.json - should-trigger and should-not-trigger prompts for discovery testing

Generic reusable templates remain in templates/. </evaluation_index>

<yaml_requirements> ⚠️ THE MOST IMPORTANT PART OF ANY SKILL ⚠️

The name and description determine whether an agent will EVER use your skill. Get these wrong and the skill is useless — it will sit unused while the agent struggles without it.

---
name: skill-name          # lowercase-with-hyphens, matches directory
description: "..."        # What it does AND when to use it (address agent as you) - MUST be quoted
---

Description MUST include:

1. What the skill does (capabilities)
2. ALL activities covered — If the skill handles creating, reviewing, updating, and auditing, say so explicitly. Users phrase requests differently ("assess", "check", "audit", "review", "modify", "update", "create", "build"). If any should trigger your skill, include them.
3. When to use it (trigger conditions)
4. Action words like "MUST be loaded before..." or "Use PROACTIVELY when..." for skills that should auto-invoke

Description MUST NOT include:

• Implementation details (file structure, tools used, architectural patterns, internal mechanisms)
• How the skill works internally — the description is for matching user intent, not explaining internals
• The description is a matching surface, not documentation. Every word should help the agent decide "does this skill apply to what the user asked?" If a word doesn't help with that decision, remove it.

Critical insight: If an agent doesn't invoke your skill, it's almost always because the description didn't match how the user phrased their request. Test against multiple phrasings.

Read knowledge/skill-structure.md for comprehensive guidance on getting this right.

Naming conventions (gerund form required):

• Use gerund (verb ending in -ing): developing-*, processing-*, managing-*, setting-up-*
• Use plural nouns: developing-skills, processing-images, managing-ads
• Avoid: vague names (helper, utils) and provider names unless the skill is truly provider-specific </yaml_requirements>

<success_criteria> A well-structured skill:

• Has valid YAML frontmatter
• Uses XML-first structure (SKILL.md body sections are semantic XML)
• Has essential principles inline in SKILL.md
• Routes directly to appropriate workflows based on user intent
• Targets SKILL.md under 500 lines
• Uses knowledge/ as an LLM Wiki-style compiled knowledge layer
• Treats behavior evaluation and description-trigger testing as first-class quality checks
• Asks minimal clarifying questions only when truly needed </success_criteria>