Skip to content
Skills Library
AI & agents · Learning & explanation

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

Repository
gsd-2 ↗
Licence
MIT
Last repository change
22.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
25
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. How Skills Work
  2. Understanding User Intent
  3. Skill Structure Quick Reference
  4. Domain Knowledge
  5. Workflows
  6. YAML Frontmatter
Original SKILL.md headings · 183 lines, 773 words
SKILL.md preview
---
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.
---

<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:
```xml
<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:**
- Global: `~/.agents/skills/{skill-name}/`
- Project-local: `.agents/skills/{skill-name}/`

**Simple skill (single file):**
```yaml
---
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:
```yaml
---
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-*`
</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>
Files in this package (25)
  • SKILL.md 6 KB
  • references/api-security.md 6 KB
  • references/be-clear-and-direct.md 13 KB
  • references/common-patterns.md 14 KB
  • references/core-principles.md 12 KB
  • references/executable-code.md 4 KB
  • references/gsd-skill-ecosystem.md 3 KB
  • references/iteration-and-testing.md 13 KB
  • references/recommended-structure.md 4 KB
  • references/skill-structure.md 11 KB
  • references/use-xml-tags.md 11 KB
  • references/using-scripts.md 3 KB
  • references/using-templates.md 3 KB
  • references/workflows-and-validation.md 12 KB
  • templates/router-skill.md 1 KB
  • templates/simple-skill.md 1 KB
  • workflows/add-reference.md 2 KB
  • workflows/add-script.md 2 KB
  • workflows/add-template.md 2 KB
  • workflows/add-workflow.md 3 KB
  • workflows/audit-skill.md 4 KB
  • workflows/create-new-skill.md 6 KB
  • workflows/get-guidance.md 3 KB
  • workflows/upgrade-to-router.md 4 KB
  • workflows/verify-skill.md 5 KB

Versions

RepositoryScoreLicence
This page · gsd-build/gsd-2100MIT
mgiovani/cc-arsenal100MIT
zylos-ai/zylos-core100MIT
mthines/agent-skills100MIT
jongio/skills100MIT
fairladyz625/harness-anything100AGPL-3.0
coco-research/coco100MIT
builderio/agent-native100MIT
BrandeisPatrick/silo-harness100MIT

Database snapshot: 13.11.2026 · package version 39a97161b53c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-agent-skills
    Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
  • 100create-agent-skills
    Expert guidance for creating agent skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
  • 100create-agent-skills
    Expert guidance for creating Claude Code skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
  • 92create-agent-skills
    Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure, progressive disclosure, workflows, validation patterns, and XML formatting.
  • 95creating-agent-skills
    Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
  • 95creating-agent-skills
    Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.