mikekelly/developing-skills

<essential_principles> Skills are modular, filesystem-based capabilities that provide domain expertise on demand.

1. Name and Description Are CRITICAL — The name and description are the ONLY way agents discover and decide to use a skill. If these are wrong, the skill will never be invoked. Treat them as the most important lines in the entire skill. See knowledge/skill-structure.md for detailed guidance.

2. Skills Are Prompts — All prompting best practices apply. Be clear, be direct, use XML structure. Assume the agent is capable - only add context it does not already have.

3. SKILL.md Is Always Loaded — When invoked, the agent 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 knowledge/

4. Router Pattern for Complex Skills

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

SKILL.md routes to workflow → workflow specifies which knowledge files to read.

5. Knowledge Follows LLM Wiki Principles — Treat knowledge/ as a persistent, compiled Markdown knowledge layer, not a dump of raw sources. Preserve source-of-truth materials outside the skill when needed; synthesize the durable guidance into focused, interlinked knowledge files. Maintain knowledge_index as a top-level map of entry points, not an exhaustive manifest; let the corpus be traversed through links and workflow-required reading.

6. Progressive Disclosure — Target SKILL.md under 500 lines. Split detailed content into knowledge files. Load only what's essential to make common activities fast and detailed aspects of the skill discoverable.

7. Challenge Every Token — Context window is shared. Before adding content, ask: "Does the agent already know this?" If in doubt, leave it out.

8. Skills Can Be Standalone Repos — Skills can live in personal skills directories or as standalone GitHub repos (distributable). Detect context and confirm intent.

9. Lack of Surprise — A skill's behavior and contents should not surprise the user given its name and description. Do not create misleading skills or skills that enable unauthorized access, credential exposure, data exfiltration, or other harmful behavior. </essential_principles>

<intake> What would you like to do?

1. Create new skill
2. Audit/modify existing skill
3. Add component (workflow, knowledge, template, or script)
4. Evaluate/benchmark skill behavior
5. Optimize skill description/triggers
6. Get guidance

If the user's intent is already clear, route directly instead of asking this menu. Ask only for missing information that materially affects the result. </intake>

<routing>

| Option | Keywords | Next Action | Workflow | |--------|----------|-------------|----------| | 1 | create / new / build / develop | If type is unclear, ask: "Task-execution skill or domain expertise skill?" | Route to appropriate develop workflow | | 2 | audit / review / assess / check | Use provided/current skill path if clear; otherwise ask for path | workflows/audit-skill.md | | 2 | modify / update / improve / fix | Use provided/current skill path if clear; otherwise ask what to change | Route to matching add/upgrade/optimize workflow | | 3 | add workflow / add knowledge / add template / add script | Route directly when component type is named; otherwise ask component type | workflows/add-{type}.md | | 4 | evaluate / benchmark / test / eval | Use provided/current skill path if clear; ask only for desired rigor if it matters | workflows/evaluate-skill.md | | 5 | description / trigger / optimize | Use provided/current skill path if clear | workflows/optimize-description.md | | 6 | guidance / help | General guidance | workflows/get-guidance.md |

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. </routing>

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

<validation> Run `ruby scripts/validate-repo.rb` after structural, workflow, template, eval, or reference changes to catch frontmatter, JSON, workflow-section, stale-pattern, and broken-reference regressions. </validation>

<workflows_index> All in workflows/:

| Workflow | Purpose | |----------|---------| | develop-new-skill.md | Build a skill from scratch | | develop-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 | | evaluate-skill.md | Run behavioral evals and compare against a baseline | | optimize-description.md | Improve trigger accuracy for the skill description | | add-workflow.md | Add a workflow to existing skill | | add-knowledge.md | Add a knowledge file 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 |

</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>