Align writing-skills with Anthropic's new Complete Guide to Building Skills

[harrymunro]

First off — thanks for building superpowers, @obra. I use it every day and it's genuinely changed how I work with Claude. Really appreciate you maintaining this.

---

Anthropic just dropped their official skill-authoring playbook today — The Complete Guide to Building Skills for Claude — and it's packed with stuff that wasn't in the docs before. This PR brings all that new goodness into the writing-skills skill.

What's actually in the guide that we were missing?

Turns out Anthropic has been watching how early adopters and internal teams build skills, and they've codified a bunch of patterns and practical guidance that goes way beyond the existing docs page. Things like:

• 5 named skill patterns they've seen work well (sequential workflows, multi-MCP coordination, iterative refinement, etc.)
• A proper troubleshooting guide for when skills won't upload, don't trigger, trigger too much, or just get ignored
• Planning guidance — use case categories, success criteria with actual metrics, the problem-first vs tool-first framing
• Extended YAML frontmatter — there are optional fields now (license, compatibility, allowed-tools, metadata) plus security rules we should know about
• The description formula — [What it does] + [When to use it] + [Key capabilities] — which nicely complements the CSO insight we already had about not putting workflow steps in descriptions
• Distribution and API guidance — /v1/skills endpoint, org-level deployment, the open standard vision
• The skill-creator tool — a built-in way to generate and review skills

How this PR is structured (eating our own cooking)

Rather than dumping 300+ lines into anthropic-best-practices.md (which would violate the progressive disclosure principle the guide itself teaches), the new content lives in focused reference files:

File	Lines	What's in it
planning-and-design.md	129	Use case categories, success criteria, testing approach, distribution
skill-patterns.md	162	The 5 patterns with examples
troubleshooting.md	123	Common issues and fixes

The existing files get concise cross-references instead of bloat:

• anthropic-best-practices.md — only +16 lines (was 1,150 → now 1,166). Adds the frontmatter fields, naming rules, description formula, and links to the new files.
• SKILL.md — only +15 lines. Reconciles the description guidance and adds cross-references.

The one interesting nuance

The Anthropic guide says descriptions should include "what it does + when to use it", but our SKILL.md previously said "NEVER include what the skill does — only triggering conditions." These aren't actually contradictory once you split it three ways:

• WHAT it does (capabilities) = good, helps Claude decide relevance
• WHEN to use it (triggers) = good, helps Claude decide timing
• HOW it works (workflow steps) = bad, creates a shortcut Claude will take

The updated SKILL.md now frames it as "WHAT + WHEN, never HOW" — which keeps the critical CSO insight while aligning with Anthropic's formula.

Test plan

• Verify markdown renders correctly in all files
• Check cross-references between files are valid
• Confirm no existing guidance was removed (this is purely additive)
• Verify the new reference files follow the same patterns as existing ones (testing-skills-with-subagents.md, persuasion-principles.md, etc.)

[coderabbitai]

📝 Walkthrough

Walkthrough

Updates the writing-skills documentation: formalizes SKILL frontmatter (required name/description, optional license, compatibility, allowed-tools, metadata), tightens naming/file rules, introduces a description formula (WHAT + WHEN + capabilities), and adds new planning, patterns, and troubleshooting guides.

Changes

Cohort / File(s)	Summary
Core skill spec skills/writing-skills/SKILL.md	Rewrote SKILL.md to require a two-field frontmatter (name, description) with expanded optional fields and stricter description rules emphasizing WHAT+WHEN+capabilities; added examples, trigger-phrase guidance, and cross-references.
Best-practices & naming rules skills/writing-skills/anthropic-best-practices.md	Formalized frontmatter schema (kebab-case name rules, reserved prefixes, max lengths), added security note (no XML angle brackets), introduced “Critical naming and file rules” and a description formula with examples.
Design & patterns skills/writing-skills/planning-and-design.md, skills/writing-skills/skill-patterns.md	Added new guidance for planning, success criteria, testing approaches, and five concrete skill-pattern templates (sequential orchestration, multi-MCP, iterative refinement, context-aware tool selection, domain-specific intelligence).
Troubleshooting skills/writing-skills/troubleshooting.md	New troubleshooting checklist covering invalid frontmatter, naming errors, trigger issues, MCP connections, large contexts, and iteration signals.
Structural / cross-ref updates skills/writing-skills/...	Inserted “See also” links and cross-references between SKILL.md, best-practices, planning-and-design, skill-patterns, and troubleshooting; adjusted examples and removed/rewrote BAD/GOOD description samples to match new formula.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Add personal superpowers overlay system #2 — Modifies writing-skills documentation and frontmatter conventions in the same directory.

Poem

🐇 I hopped through docs both near and far,

polished names, and trimmed the jar.
WHAT and WHEN now brightly shine,
patterns, tests, and notes align.
Hop on—this skill will work just fine! ✨

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main objective: aligning the writing-skills documentation with Anthropic's new Complete Guide to Building Skills, which is directly reflected in the file changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main
Description check	✅ Passed	The pull request description is directly related to the changeset, clearly explaining how Anthropic's official skill-authoring guide is being integrated into the writing-skills documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[obra]

Thanks for this, and for linking the Anthropic guide! v5.0.0 reworked several of the skills this touches. Closing as stale — if you'd like to revisit against the current codebase, we'd welcome a fresh PR.

— Claude (claude-opus-4-6, Claude Code 2.1.71, session 64908a66-5c98-4c79-b0f7-1aa7eac2dcb0)