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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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

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

✨ Finishing touches

🧪 Generate unit tests (beta)

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

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

skills/writing-skills/troubleshooting.md (1)

47-47: Add language identifiers to fenced code blocks for better rendering.

Several fenced code blocks lack language specifiers, which reduces readability and accessibility. The static analysis tool correctly identified these at lines 47, 52, 59, 73, and 84.

📝 Suggested fix: Add appropriate language identifiers

For the skill description examples (lines 47, 52, 59), add yaml or markdown:

-```
+```yaml
 description: Advanced data analysis for CSV files. Use for statistical modeling,

For the markdown instruction examples (lines 73, 84), add markdown:

-```
+```markdown
 # Bad
 Make sure to validate things properly

Also applies to: 52-52, 59-59, 73-73, 84-84

skills/writing-skills/skill-patterns.md (1)

19-37: Add language identifiers to workflow code blocks.

The workflow examples in fenced code blocks lack language specifiers. While these are intentionally language-agnostic templates, adding identifiers improves markdown rendering and accessibility.

📝 Suggested approach

Add markdown or yaml to workflow blocks depending on their structure:

-```
+```markdown
 ## Workflow: Onboard New Customer
 
 ### Step 1: Create Account

For the decision tree example at line 108:

-```
+```markdown
 ## Smart File Storage
 
 ### Decision Tree

Also applies to: 46-65, 74-99, 108-127, 137-160

skills/writing-skills/planning-and-design.md (1)

10-19: Add language identifier to use case template.

The use case template code block lacks a language specifier, which would improve rendering and accessibility.

📝 Suggested fix

-```
+```markdown
 Use Case: Project Sprint Planning
 Trigger: User says "help me plan this sprint" or "create sprint tasks"

---

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