create-skill

Based on the user's message, route directly to the appropriate workflow:

Creating new skills:

• Domain expertise (exhaustive knowledge base) → Use create-domain-expertise skill instead (separate skill with batched subagent orchestration)
• Task-execution skill (does specific things) → workflows/create-new-skill.md

Working with existing skills:

• Audit, review, check → workflows/audit-skill.md
• Verify content is current → workflows/verify-skill.md
• Add workflow → workflows/add-workflow.md
• Add reference → workflows/add-reference.md
• Add template → workflows/add-template.md
• Add script → workflows/add-script.md
• Upgrade to router pattern → workflows/upgrade-to-router.md

Need help deciding:

• General guidance → workflows/get-guidance.md

If user intent is unclear, ask minimal clarifying questions:

• "Create a MIDI skill" → "Task-execution skill (does MIDI tasks) or domain expertise (complete MIDI knowledge base)?"
• "Work on my skill" → "Which skill? What do you want to do with it?"
• Ask one clarifying question round at a time, then wait for the user's actual response before asking another.
• Never fabricate or simulate user responses while clarifying (for example, fake [User] markers or imagined answers).

Then proceed directly to the workflow.

<quick_reference>

Skill Structure Quick Reference

Skill directories:

• Bundled/read-only: ~/.gsd/agent/skills/{skill-name}/
• Global: ~/.agents/skills/{skill-name}/
• Project-local: .agents/skills/{skill-name}/

User-authored skills should target the global or project-local directories; GSD manages the bundled directory during install/update.

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 Claude copies and fills
  (plans, specs, configs, documents)

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

</quick_reference>

<reference_index>

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 GSD-specific: gsd-skill-ecosystem.md </reference_index>

<workflows_index>

Workflows

All in workflows/:

<yaml_requirements>

YAML Frontmatter

Required fields:

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

Frontmatter must parse as YAML. Quote description values containing : or use a folded block (description: >) for longer trigger descriptions.

Name conventions: create-*, manage-*, setup-*, generate-*, build-* </yaml_requirements>

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