AGENT SKILL

create-skill

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

License 许可
MIT
所属仓库
open-gsd/gsd-pi
最近更新
2026-11-15
Stars
★ 1.4k
Forks
118

01 前言 Front Matter

name
create-skill
description
Expert guidance for creating, writing, building, and refining GSD skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.

02 资源文件 24

03 SKILL.md 正文

<essential_principles>

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

<routing>

Understanding User Intent

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

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

Workflow Purpose
create-new-skill.md Build a task-execution skill from scratch
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
</workflows_index>

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

04 同仓库更多 Skills

open-gsd
open-gsd/gsd-pi

write-milestone-brief

Synthesize the current conversation into a milestone brief (PRD). Saves it as the milestone CONTEXT (`gsd_summary_save`) by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.

★ 1.4k
open-gsd
open-gsd/gsd-pi

write-docs

Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.

★ 1.4k
open-gsd
open-gsd/gsd-pi

web-quality-audit

Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".

★ 1.4k
open-gsd
open-gsd/gsd-pi

web-design-guidelines

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

★ 1.4k
open-gsd
open-gsd/gsd-pi

verify-before-complete

Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.

★ 1.4k
open-gsd
open-gsd/gsd-pi

userinterface-wiki

UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.

★ 1.4k