Skip to content

tobihagemann/turbo / claude/skills/write-skill

write-skill

Verified

Create or update a skill that extends Claude's capabilities. Use when the user asks to "create a skill", "make a new skill", "write a skill for...", or "update this skill".

FileKindSize
SKILL.mdskill md9.9 KB
references/composition.mdmarkdown4.6 KB
references/evaluation.mdmarkdown3.9 KB
references/harness.mdmarkdown2.9 KB
references/principles.mdmarkdown7.3 KB
references/scripts.mdmarkdown4.4 KB
references/skill-reviewer.mdmarkdown5.7 KB
references/structure.mdmarkdown9.4 KB
references/tools.mdmarkdown28.1 KB
references/workflows.mdmarkdown8.0 KB
references/writing.mdmarkdown8.1 KB

references/structure.md

View on GitHub
# Skill Metadata and Structure

Frontmatter rules, naming, and how to lay out a skill directory so Claude loads only what it needs.

## Contents

- YAML Frontmatter
- Naming Conventions
- Writing Effective Descriptions
- Progressive Disclosure Patterns
- Avoid Deeply Nested References
- Separation of Concerns Between Layers
- Use Forward Slashes in Paths
- Compute Relative Paths from the File's Actual Location
- Structure Longer Reference Files with Table of Contents

## YAML Frontmatter

The SKILL.md frontmatter requires two fields:

`name`:

- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"

`description`:

- Must be non-empty
- Maximum 1024 characters
- Stay within 200 characters of the parsed value
- Among the trigger phrases, keep one built on the skill's name and spend the rest on phrasings a user would type that the summary's own words do not already cover
- Cannot contain XML tags or angle brackets; write a placeholder in square brackets, such as `[slug]`
- Should describe what the Skill does and when to use it

**Quoting values**: Quote frontmatter values that contain YAML special characters. Unquoted `: ` (colon-space) breaks parsing. When in doubt, wrap the value in double quotes and escape inner quotes with `\"`.

```yaml
# Bad — colon-space breaks YAML parsing
description: Handles two modes: draft and final

# Good — quoted value
description: "Handles two modes: draft and final"
```

## Naming Conventions

Use consistent naming patterns to make Skills easier to reference and discuss. Consider using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.

Remember that the `name` field must use lowercase letters, numbers, and hyphens only.

**Good naming examples (gerund form)**:

- `processing-pdfs`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `writing-documentation`

**Acceptable alternatives**:

- Noun phrases: `pdf-processing`, `spreadsheet-analysis`
- Action-oriented: `process-pdfs`, `analyze-spreadsheets`

**Avoid**:

- Vague names: `helper`, `utils`, `tools`
- Overly generic: `documents`, `data`, `files`
- Reserved words: `anthropic-helper`, `claude-tools`
- Inconsistent patterns within your skill collection

## Writing Effective Descriptions

The `description` field enables Skill discovery and should include both what the Skill does and when to use it.

> **Warning: Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
>
> - **Good:** "Processes Excel files and generates reports"
> - **Avoid:** "I can help you process Excel files"
> - **Avoid:** "You can use this to process Excel files"

**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.

Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.

An effective description names the concrete operations and then the trigger contexts and user phrasings that should activate the skill. Avoid vague descriptions like `Helps with documents`, `Processes data`, or `Does stuff with files`.

## Progressive Disclosure Patterns

SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide.

**Practical guidance:**

- Keep SKILL.md body under about 3,000 words (roughly 5k tokens) for optimal performance
- When approaching this limit, move only content a typical run does not read into separate files, and keep the rest in the body even when that leaves it over the limit
- Use the patterns below to organize instructions, code, and resources effectively

A Skill can grow from a single SKILL.md to a directory of bundled content that Claude loads only when needed:

```text
skill-name/
├── SKILL.md              # Main instructions (loaded when triggered)
├── references/
│   ├── advanced.md       # Loaded as needed
│   └── reference.md      # API reference (loaded as needed)
└── scripts/
    ├── analyze.py        # Utility script (executed, not loaded)
    └── validate.py       # Validation script
```

Four patterns cover most cases:

- **High-level guide with references** — SKILL.md carries a quick-start path inline and links out to one file per advanced topic. Claude loads a linked file only when the task reaches that topic.
- **Domain-specific organization** — for Skills spanning multiple domains, give each domain its own reference file so a question about one domain never loads the others. Pair this with a grep hint in SKILL.md when the files are large enough that Claude should search rather than read them whole.
- **Conditional details** — keep the common path inline and link out only the branches, so the rare or heavyweight branch costs nothing on a typical run.
- **Frequency of need** — content read once at setup (installation, provisioning, credentials, permission and role setup) or only on failure (troubleshooting tables, error-code references) belongs in a reference file, even when it is topically core to the skill. Ask whether Claude doing this skill's normal job would read it every time, or once at setup and again when something breaks.

## Avoid Deeply Nested References

Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.

**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.

- ✗ **Avoid**: SKILL.md links to `advanced.md`, which links to `details.md`, which holds the actual information.
- ✓ **Good**: SKILL.md links directly to `advanced.md`, `reference.md`, and `examples.md`, each self-contained.

## Separation of Concerns Between Layers

When SKILL.md links to sub-files, each layer must own exactly one concern:

- **SKILL.md (router)**: Routing decisions, shared config, links to sub-files. Does not summarize or repeat sub-file content.
- **Sub-files (leaves)**: Self-contained instructions for one mode or topic. Assumes the routing decision is already made. Does not contain cross-mode routing tables.

Routing tables, decision logic, and shared config belong in SKILL.md only. Sub-files should never route back to siblings, and SKILL.md should not summarize sub-file commands. When other skills reference a sub-file, they should point to the skill and name the sub-file: "Run `/skill-name` skill and consult sub-file.md to ..."

### Moving Content

When removing content from a router because a sub-file already covers it, check whether the router loses a warning the sub-file cannot deliver. A sub-file reaches only a reader who already decided to look, so a caution against a wrong inference has to survive in the router. Merge such a line into the surrounding routing prose rather than deleting it.

When moving a rule from the router into a sub-file, find every router step that reached the rule where it stood, and link each one to the sub-file.

When moving a section into a sub-file or into another skill, list before the move every behavior and special case the moved text performs, every definition or placeholder that the text staying behind still uses, and every condition reworded on the way. After the move, confirm each still holds somewhere with its original scope. A dropped special case, an orphaned placeholder, or a condition widened by generic rewording survives review, because every remaining sentence still reads as sound.

## Use Forward Slashes in Paths

Always use forward slashes in file paths, even on Windows:

- ✓ **Good**: `scripts/helper.py`, `reference/guide.md`
- ✗ **Avoid**: `scripts\helper.py`, `reference\guide.md`

Unix-style paths work across all platforms; Windows-style paths cause errors on Unix systems.

## Compute Relative Paths from the File's Actual Location

When a skill file references another file in the same skill, the relative path resolves from the file's own location, not from `SKILL.md`. A reference file at `skills/X/references/foo.md` linking to a sibling at `skills/X/references/bar.md` writes `bar.md`, not `references/bar.md`.

Use markdown links rather than inline code for cross-references. `[bar.md](bar.md)` matches how `SKILL.md` links to its references and how skills link to each other; inline `` `bar.md` `` reads as a path mention but loses the click-through and the convention.

- ✗ **Avoid**: From `skills/X/references/foo.md`: "follow `references/bar.md`" — broken path; not a link.
- ✓ **Good**: From `skills/X/references/foo.md`: "follow [bar.md](bar.md)".

## Structure Longer Reference Files with Table of Contents

For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads. List the section headings under a `## Contents` heading near the top of the file, then the sections themselves.

Claude can then read the complete file or jump to specific sections as needed.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall