Reenforce writing-skills with latest Anthropic "Building Skills" Guide

[nguyenjulian]

Is your feature request related to a problem? Please describe.
Not a problem, but I think that writing-skills could be made better

Describe the solution you'd like
Add the teachings, guidelines, and suggested patterns described in https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en to writing-skills

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

[kierr]

@coderabbitai below is a very dirty paste of the PDF, access/parse the PDF URL above if you can. reflect, ponder, research, to determine how to effectively incorporate the insights from the PDF into writing-skills and potentially other skills, too

---

The Complete Guide
to Building Skills
for Claude
Contents
Introduction 3
Fundamentals 4
Planning and design 7
Testing and iteration 14
Distribution and sharing 18
Patterns and troubleshooting 21
Resources and references 28
2
Introduction
A skill is a set of instructions - packaged as a simple folder - that teaches Claude
how to handle specific tasks or workflows. Skills are one of the most powerful
ways to customize Claude for your specific needs. Instead of re-explaining your
preferences, processes, and domain expertise in every conversation, skills let you
teach Claude once and benefit every time.
Skills are powerful when you have repeatable workflows: generating frontend
designs from specs, conducting research with consistent methodology, creating
documents that follow your team's style guide, or orchestrating multi-step
processes. They work well with Claude's built-in capabilities like code execution
and document creation. For those building MCP integrations, skills add another
powerful layer helping turn raw tool access into reliable, optimized workflows.
This guide covers everything you need to know to build effective skills - from
planning and structure to testing and distribution. Whether you're building a
skill for yourself, your team, or for the community, you'll find practical patterns
and real-world examples throughout.
What you'll learn:
•
Technical requirements and best practices for skill structure
•
Patterns for standalone skills and MCP-enhanced workflows
•
Patterns we've seen work well across different use cases
•
How to test, iterate, and distribute your skills
Who this is for:
•
Developers who want Claude to follow specific workflows consistently
•
Power users who want Claude to follow specific workflows
•
Teams looking to standardize how Claude works across their organization
Two Paths Through This Guide
Building standalone skills? Focus on Fundamentals, Planning and Design, and
category 1-2. Enhancing an MCP integration? The "Skills + MCP" section and
category 3 are for you. Both paths share the same technical requirements, but
you choose what's relevant to your use case.
What you'll get out of this guide: By the end, you'll be able to build a functional
skill in a single sitting. Expect about 15-30 minutes to build and test your first
working skill using the skill-creator.
Let's get started.
Chapter 1
Fundamentals
4
Chapter 1
Fundamentals
What is a skill?
A skill is a folder containing:
•
SKILL.md (required): Instructions in Markdown with YAML frontmatter
•
scripts/ (optional): Executable code (Python, Bash, etc.)
•
references/ (optional): Documentation loaded as needed
•
assets/ (optional): Templates, fonts, icons used in output
Core design principles
Progressive Disclosure
Skills use a three-level system:
•
First level (YAML frontmatter): Always loaded in Claude's system prompt.
Provides just enough information for Claude to know when each skill should
be used without loading all of it into context.
•
Second level (SKILL.md body): Loaded when Claude thinks the skill is
relevant to the current task. Contains the full instructions and guidance.
•
Third level (Linked files): Additional files bundled within the skill directory
that Claude can choose to navigate and discover only as needed.
This progressive disclosure minimizes token usage while maintaining
specialized expertise.
Composability
Claude can load multiple skills simultaneously. Your skill should work well
alongside others, not assume it's the only capability available.
Portability
Skills work identically across Claude.ai, Claude Code, and API. Create a skill once
and it works across all surfaces without modification, provided the environment
supports any dependencies the skill requires.
For MCP Builders: Skills + Connectors
💡 Building standalone skills without MCP? Skip to Planning and Design - you can
always return here later.
If you already have a working MCP server, you've done the hard part. Skills are
the knowledge layer on top - capturing the workflows and best practices you
already know, so Claude can apply them consistently.
The kitchen analogy
MCP provides the professional kitchen: access to tools, ingredients, and
equipment.
Skills provide the recipes: step-by-step instructions on how to create something
valuable.
5
Together, they enable users to accomplish complex tasks without needing to
figure out every step themselves.
How they work together:
MCP (Connectivity) Skills (Knowledge)
Connects Claude to your service
(Notion, Asana, Linear, etc.)
Teaches Claude how to use your service
effectively
Provides real-time data access and tool
invocation
Captures workflows and best practices
What Claude can do How Claude should do it
Why this matters for your MCP users
Without skills:
•
•
•
•
•
Users connect your MCP but don't know what to do next
Support tickets asking "how do I do X with your integration"
Each conversation starts from scratch
Inconsistent results because users prompt differently each time
Users blame your connector when the real issue is workflow guidance
With skills:
•
•
•
•
Pre-built workflows activate automatically when needed
Consistent, reliable tool usage
Best practices embedded in every interaction
Lower learning curve for your integration
6
Chapter 2
Planning and design
7
Chapter 2
Planning and design
Start with use cases
Before writing any code, identify 2-3 concrete use cases your skill should enable.
Good use case definition:
Use Case: Project Sprint Planning
Trigger: User says "help me plan this sprint" or "create
sprint tasks"
Steps:

1. Fetch current project status from Linear (via MCP)
2. Analyze team velocity and capacity
3. Suggest task prioritization
4. Create tasks in Linear with proper labels and estimates
   Result: Fully planned sprint with tasks created
   Ask yourself:
   •
   •
   •
   •
   What does a user want to accomplish?
   What multi-step workflows does this require?
   Which tools are needed (built-in or MCP?)
   What domain knowledge or best practices should be embedded?
   Common skill use case categories
   At Anthropic, we’ve observed three common use cases:
   Category 1: Document & Asset Creation
   Used for: Creating consistent, high-quality output including documents,
   presentations, apps, designs, code, etc.
   Real example: frontend-design skill (also see skills for docx, pptx, xlsx, and
   ppt)
   "Create distinctive, production-grade frontend interfaces with high design
   quality. Use when building web components, pages, artifacts, posters, or
   applications."
   Key techniques:
   •
   •
   •
   •
   Embedded style guides and brand standards
   Template structures for consistent output
   Quality checklists before finalizing
   No external tools required - uses Claude's built-in capabilities
   8
   Category 2: Workflow Automation
   Used for: Multi-step processes that benefit from consistent methodology,
   including coordination across multiple MCP servers.
   Real example: skill-creator skill
   "Interactive guide for creating new skills. Walks the user through use case
   definition, frontmatter generation, instruction writing, and validation."
   Key techniques:
   •
   Step-by-step workflow with validation gates
   •
   Templates for common structures
   •
   Built-in review and improvement suggestions
   •
   Iterative refinement loops
   Category 3: MCP Enhancement
   Used for: Workflow guidance to enhance the tool access an MCP server provides.
   Real example: sentry-code-review skill (from Sentry)
   "Automatically analyzes and fixes detected bugs in GitHub Pull Requests using
   Sentry's error monitoring data via their MCP server."
   Key techniques:
   •
   •
   •
   •
   Coordinates multiple MCP calls in sequence
   Embeds domain expertise
   Provides context users would otherwise need to specify
   Error handling for common MCP issues
   Define success criteria
   How will you know your skill is working?
   These are aspirational targets - rough benchmarks rather than precise
   thresholds. Aim for rigor but accept that there will be an element of vibes-based
   assessment. We are actively developing more robust measurement guidance and
   tooling.
   Quantitative metrics:
   •
   Skill triggers on 90% of relevant queries
   – How to measure: Run 10-20 test queries that should trigger your skill. Track
   how many times it loads automatically vs. requires explicit invocation.
   •
   Completes workflow in X tool calls
   – How to measure: Compare the same task with and without the skill enabled.
   Count tool calls and total tokens consumed.
   •
   0 failed API calls per workflow
   – How to measure: Monitor MCP server logs during test runs. Track retry rates
   and error codes.
   Qualitative metrics:
   •
   Users don't need to prompt Claude about next steps
   – How to assess: During testing, note how often you need to redirect or clarify.
   Ask beta users for feedback.
   •
   •
   Workflows complete without user correction
   – How to assess: Run the same request 3-5 times. Compare outputs for
   structural consistency and quality.
   Consistent results across sessions
   – How to assess: Can a new user accomplish the task on first try with minimal
   guidance?
   9
   Technical requirements
   File structure
   YAML frontmatter: The most important part
   The YAML frontmatter is how Claude decides whether to load your skill. Get this
   right.
   your-skill-name/
   ├── SKILL.md # Required - main skill file
   ├── scripts/ # Optional - executable code
   │ ├── process_data.py # Example
   │ └── validate.sh # Example
   ├── references/ # Optional - documentation
   │ ├── api-guide.md # Example
   │ └── examples/ # Example
   └── assets/ # Optional - templates, etc.
   └── report-template.md # Example
   Minimal required format

---

name: your-skill-name
description: What it does. Use when user asks to [specific
phrases].

Critical rules
SKILL.md naming:
•
Must be exactly SKILL.md (case-sensitive)
•
No variations accepted (SKILL.MD, skill.md, etc.)
Skill folder naming:
•
Use kebab-case: notion-project-setup ✅
•
No spaces: Notion Project Setup ❌
•
No underscores: notion_project_setup ❌
•
No capitals: NotionProjectSetup ❌
That's all you need to start.
Field requirements
name (required):
•
kebab-case only
•
No spaces or capitals
•
Should match folder name
description (required):
•
MUST include BOTH:
– What the skill does
– When to use it (trigger conditions)
•
Under 1024 characters
•
No XML tags (< or >)
•
Include specific tasks users might say
•
Mention file types if relevant
No README.md:
•
•
•
Don't include README.md inside your skill folder
All documentation goes in SKILL.md or references/
Note: when distributing via GitHub, you'll still want a repo-level README for
human users — see Distribution and Sharing.
10
license (optional):
•
Use if making skill open source
•
Common: MIT, Apache-2.0
compatibility (optional)
•
1-500 characters
•
Indicates environment requirements: e.g. intended product, required system
packages, network access needs, etc.
metadata (optional):
•
Any custom key-value pairs
•
Suggested: author, version, mcp-server
•
Example:

metadata:
author: ProjectHub
version: 1.0.0 mcp-server: projecthub

Security restrictions
Forbidden in frontmatter:
•
XML angle brackets (< >)
•
Skills with "claude" or "anthropic" in name (reserved)
Why: Frontmatter appears in Claude's system prompt. Malicious content could
inject instructions.
Writing effective skills
The description field
According to Anthropic's engineering blog: "This metadata...provides just
enough information for Claude to know when each skill should be used without
loading all of it into context." This is the first level of progressive disclosure.
Structure:
[What it does] + [When to use it] + [Key capabilities]
Examples of good descriptions:

Good - specific and actionable

description: Analyzes Figma design files and generates
developer handoff documentation. Use when user uploads .fig
files, asks for "design specs", "component documentation", or
"design-to-code handoff".

Good - includes trigger phrases

description: Manages Linear project workflows including sprint
planning, task creation, and status tracking. Use when user
mentions "sprint", "Linear tasks", "project planning", or asks
to "create tickets".

Good - clear value proposition

description: End-to-end customer onboarding workflow for
PayFlow. Handles account creation, payment setup, and
subscription management. Use when user says "onboard new
customer", "set up subscription", or "create PayFlow account".
11
Examples of bad descriptions:

Too vague

description: Helps with projects.

Missing triggers

description: Creates sophisticated multi-page documentation
systems.

Too technical, no user triggers

description: Implements the Project entity model with
hierarchical relationships.
Writing the main instructions
After the frontmatter, write the actual instructions in Markdown.
Recommended structure:
Adapt this template for your skill. Replace bracketed sections with your specific
content.

name: your-skill
description: [--.]

Your Skill Name

Instructions

--# Step 1: [First Major Step]
Clear explanation of what happens.
Example:

python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]
(Add more steps as needed)
Examples
Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link
(Add more examples as needed)
Troubleshooting
Error: [Common error message]
Cause: [Why it happens]
Solution: [How to fix]
(Add more error cases as needed)
12
Best Practices for Instructions
Reference bundled resources clearly
Be Specific and Actionable
Before writing queries, consult `references/api-patterns.md`
✅ Good:
for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling
Run `python scripts/validate.py --input {filename}` to check
data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)
❌ Bad:
Use progressive disclosure
Keep SKILL.md focused on core instructions. Move detailed documentation to
`references/` and link to it. (See Core Design Principles for how the three-
level system works.)
Validate the data before proceeding.
Include error handling
## Common Issues
--# MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] >
Reconnect
13
Chapter 3
Testing and iteration
14
Chapter 3
Testing and iteration
Skills can be tested at varying levels of rigor depending on your needs:
•
•
•
Manual testing in Claude.ai - Run queries directly and observe behavior. Fast
iteration, no setup required.
Scripted testing in Claude Code - Automate test cases for repeatable
validation across changes.
Programmatic testing via skills API - Build evaluation suites that run
systematically against defined test sets.
Choose the approach that matches your quality requirements and the visibility
of your skill. A skill used internally by a small team has different testing needs
than one deployed to thousands of enterprise users.
Pro Tip: Iterate on a single task before expanding
We’ve found that the most effective skill creators iterate on a single challenging
task until Claude succeeds, then extract the winning approach into a skill. This
leverages Claude’s in-context learning and provides faster signal than broad
testing. Once you have a working foundation, expand to multiple test cases for
coverage.
Recommended Testing Approach
Based on early experience, effective skills testing typically covers three areas:
1. Triggering tests
Goal: Ensure your skill loads at the right times.
Test cases:
•
•
•
✅ Triggers on obvious tasks
✅ Triggers on paraphrased requests
❌ Doesn't trigger on unrelated topics
Example test suite:
Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"
Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless ProjectHub skill handles
sheets)
15
2. Functional tests
Goal: Verify the skill produces correct outputs.
Test cases:
•
Valid outputs generated
•
API calls succeed
•
Error handling works
•
Edge cases covered
Example:
Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
- Project created in ProjectHub
- 5 tasks created with correct properties
- All tasks linked to project
- No API errors
3. Performance comparison
Goal: Prove the skill improves results vs. baseline.
Use the metrics from Define Success Criteria. Here's what a comparison might
look like.
Baseline comparison:
Without skill:
- User provides instructions each time
- 15 back-and-forth messages
- 3 failed API calls requiring retry
- 12,000 tokens consumed
With skill:
- Automatic workflow execution
- 2 clarifying questions only
- 0 failed API calls
- 6,000 tokens consumed
Using the skill-creator skill
The skill-creator skill - available in Claude.ai via plugin directory or
download for Claude Code - can help you build and iterate on skills. If you
have an MCP server and know your top 2–3 workflows, you can build and test a
functional skill in a single sitting - often in 15–30 minutes.
Creating skills:
•
Generate skills from natural language descriptions
•
Produce properly formatted SKILL.md with frontmatter
•
Suggest trigger phrases and structure
Reviewing skills:
•
Flag common issues (vague descriptions, missing triggers, structural
problems)
•
Identify potential over/under-triggering risks
•
Suggest test cases based on the skill's stated purpose
Iterative improvement:
•
After using your skill and encountering edge cases or failures, bring those
examples back to skill-creator
•
Example: "Use the issues & solution identified in this chat to improve how the
skill handles [specific edge case]"
16
To use:
"Use the skill-creator skill to help me build a skill for
[your use case]"
Execution issues:
•
•
•
Inconsistent results
API call failures
User corrections needed
Note: skill-creator helps you design and refine skills but does not execute
automated test suites or produce quantitative evaluation results.
Solution: Improve instructions, add error handling
Iteration based on feedback
Skills are living documents. Plan to iterate based on:
Undertriggering signals:
•
•
•
Skill doesn't load when it should
Users manually enabling it
Support questions about when to use it
Solution: Add more detail and nuance to the description - this may include
keywords particularly for technical terms
Overtriggering signals:
•
•
•
Skill loads for irrelevant queries
Users disabling it
Confusion about purpose
Solution: Add negative triggers, be more specific
17
Chapter 4
Distribution and
sharing
18
Chapter 4
Distribution and sharing
Skills make your MCP integration more complete. As users compare connectors,
those with skills offer a faster path to value, giving you an edge over MCP-only
alternatives.
Current distribution model (January 2026)
How individual users get skills:
1. Download the skill folder
2. Zip the folder (if needed)
3. Upload to Claude.ai via Settings > Capabilities > Skills
4. Or place in Claude Code skills directory
Organization-level skills:
•
Admins can deploy skills workspace-wide (shipped December 18, 2025)
•
Automatic updates
•
Centralized management
An open standard
We've published Agent Skills as an open standard. Like MCP, we believe skills
should be portable across tools and platforms - the same skill should work
whether you're using Claude or other AI platforms. That said, some skills are
designed to take full advantage of a specific platform's capabilities; authors can
note this in the skill's compatibility field. We've been collaborating with
members of the ecosystem on the standard, and we're excited by early adoption.
Using skills via API
For programmatic use cases - such as building applications, agents, or automated
workflows that leverage skills - the API provides direct control over skill
management and execution.
Key capabilities:
•
`/v1/skills` endpoint for listing and managing skills
•
Add skills to Messages API requests via the `container.skills` parameter
•
Version control and management through the Claude Console
•
Works with the Claude Agent SDK for building custom agents
When to use skills via the API vs. Claude.ai:
Use Case Best Surface
End users interacting with skills directly Claude.ai / Claude Code
Manual testing and iteration during development Claude.ai / Claude Code
Individual, ad-hoc workflows Claude.ai / Claude Code
Applications using skills programmatically API
Production deployments at scale API
Automated pipelines and agent systems API
19
Note: Skills in the API require the Code Execution Tool beta, which provides the
secure environment skills need to run.
For implementation details, see:
•
Skills API Quickstart
•
Create Custom skills
•
Skills in the Agent SDK
Recommended approach today
Start by hosting your skill on GitHub with a public repo, clear README (for
human visitors — this is separate from your skill folder, which should not contain
a README.md), and example usage with screenshots. Then add a section
to your MCP documentation that links to the skill, explains why using both
together is valuable, and provides a quick-start guide.
1. Host on GitHub
– Public repo for open-source skills
– Clear README with installation instructions
– Example usage and screenshots
2. Document in Your MCP Repo
– Link to skills from MCP documentation
– Explain the value of using both together
– Provide quick-start guide
3. Create an Installation Guide
## Installing the [Your Service] skill
1. Download the skill:
- Clone repo: `git clone https://github.com/yourcompany/
skills`
- Or download ZIP from Releases
2. Install in Claude:
- Open Claude.ai > Settings > skills
- Click "Upload skill"
- Select the skill folder (zipped)
3. Enable the skill:
- Toggle on the [Your Service] skill
- Ensure your MCP server is connected
4. Test:
- Ask Claude: "Set up a new project in [Your Service]"
Positioning your skill
How you describe your skill determines whether users understand its value and
actually try it. When writing about your skill—in your README, documentation,
or marketing - keep these principles in mind.
Focus on outcomes, not features:
✅ Good:
"The ProjectHub skill enables teams to set up complete project
workspaces in seconds — including pages, databases, and
templates — instead of spending 30 minutes on manual setup."
❌ Bad:
"The ProjectHub skill is a folder containing YAML frontmatter
and Markdown instructions that calls our MCP server tools."
Highlight the MCP + skills story:
"Our MCP server gives Claude access to your Linear projects.
Our skills teach Claude your team's sprint planning workflow.
Together, they enable AI-powered project management."
20
Chapter 5
Patterns and
troubleshooting
21
Chapter 5
Patterns and troubleshooting
These patterns emerged from skills created by early adopters and internal teams.
They represent common approaches we've seen work well, not prescriptive
templates.
Choosing your approach: Problem-first vs. tool-first
Think of it like Home Depot. You might walk in with a problem - "I need to fix a
kitchen cabinet" - and an employee points you to the right tools. Or you might
pick out a new drill and ask how to use it for your specific job.
Skills work the same way:
•
Problem-first: "I need to set up a project workspace" → Your skill orchestrates
the right MCP calls in the right sequence. Users describe outcomes; the skill
handles the tools.
•
Tool-first: "I have Notion MCP connected" → Your skill teaches Claude the
optimal workflows and best practices. Users have access; the skill provides
expertise.
Most skills lean one direction. Knowing which framing fits your use case helps
you choose the right pattern below.
Pattern 1: Sequential workflow orchestration
Use when: Your users need multi-step processes in a specific order.
Example structure:
## Workflow: Onboard New Customer
--# Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company
--# Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification
--# Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)
--# Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template
Key techniques:
•
•
•
Explicit step ordering
Dependencies between steps
Validation at each stage
•
Rollback instructions for failures
22
Pattern 2: Multi-MCP coordination
Use when: Workflows span multiple services.
Example: Design-to-development handoff
--# Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest
--# Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links
--# Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team
--# Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering
2. Include asset links and task references
Key techniques:
•
•
•
•
Clear phase separation
Data passing between MCPs
Validation before moving to next phase
Centralized error handling
Pattern 3: Iterative refinement
Use when: Output quality improves with iteration.
Example: Report generation
## Iterative Report Creation
--# Initial Draft
1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file
--# Quality Check
1. Run validation script: `scripts/check_report.py`
2. Identify issues:
- Missing sections
- Inconsistent formatting
- Data validation errors
--# Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met
--# Finalization
1. Apply final formatting
2. Generate summary
3. Save final version
Key techniques:
•
•
•
Explicit quality criteria
Iterative improvement
Validation scripts
•
Know when to stop iterating
23
Pattern 4: Context-aware tool selection
Use when: Same outcome, different tools depending on context.
Example: File storage
## Smart File Storage
--# Decision Tree
1. Check file type and size
2. Determine best storage location:
- Large files (>10MB): Use cloud storage MCP
- Collaborative docs: Use Notion/Docs MCP
- Code files: Use GitHub MCP
- Temporary files: Use local storage
--# Execute Storage
Based on decision:
- Call appropriate MCP tool
- Apply service-specific metadata
- Generate access link
--# Provide Context to User
Explain why that storage was chosen
Key techniques:
•
•
•
Clear decision criteria
Fallback options
Transparency about choices
Pattern 5: Domain-specific intelligence
Use when: Your skill adds specialized knowledge beyond tool access.
Example: Financial compliance
## Payment Processing with Compliance
--# Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
- Check sanctions lists
- Verify jurisdiction allowances
- Assess risk level
3. Document compliance decision
--# Processing
IF compliance passed:
- Call payment processing MCP tool
- Apply appropriate fraud checks
- Process transaction
ELSE:
- Flag for review
- Create compliance case
--# Audit Trail
- Log all compliance checks
- Record processing decisions
- Generate audit report
Key techniques:
•
•
•
•
Domain expertise embedded in logic
Compliance before action
Comprehensive documentation
Clear governance
24
Troubleshooting
Skill won't upload
Error: "Could not find SKILL.md in uploaded folder"
Cause: File not named exactly SKILL.md
Solution:
•
Rename to SKILL.md (case-sensitive)
•
Verify with: ls -la should show SKILL.md
Error: "Invalid frontmatter"
Cause: YAML formatting issue
Common mistakes:
# Wrong - missing delimiters
name: my-skill
description: Does things
# Wrong - unclosed quotes
name: my-skill
description: "Does things
# Correct
---
name: my-skill
description: Does things
---
Error: "Invalid skill name"
Cause: Name has spaces or capitals
# Wrong
name: My Cool Skill
# Correct
name: my-cool-skill
Skill doesn't trigger
Symptom: Skill never loads automatically
Fix:
Revise your description field. See The Description Field for good/bad examples.
Quick checklist:
•
Is it too generic? ("Helps with projects" won't work)
•
Does it include trigger phrases users would actually say?
•
Does it mention relevant file types if applicable?
Debugging approach:
Ask Claude: "When would you use the [skill name] skill?" Claude will quote the
description back. Adjust based on what's missing.
Skill triggers too often
Symptom: Skill loads for unrelated queries
Solutions:
1. Add negative triggers
description: Advanced data analysis for CSV files. Use for
statistical modeling, regression, clustering. Do NOT use for
simple data exploration (use data-viz skill instead).
25
2. Be more specific
# Too broad
description: Processes documents
# More specific
description: Processes PDF legal documents for contract review
3. Clarify scope
description: PayFlow payment processing for e-commerce. Use
specifically for online payment workflows, not for general
financial queries.
MCP connection issues
Symptom: Skill loads but MCP calls fail
Checklist:
1. Verify MCP server is connected
– Claude.ai: Settings > Extensions > [Your Service]
– Should show "Connected" status
2. Check authentication
– API keys valid and not expired
– Proper permissions/scopes granted
– OAuth tokens refreshed
3. Test MCP independently
– Ask Claude to call MCP directly (without skill)
– "Use [Service] MCP to fetch my projects"
– If this fails, issue is MCP not skill
4. Verify tool names
– Skill references correct MCP tool names
– Check MCP server documentation
– Tool names are case-sensitive
Instructions not followed
Symptom: Skill loads but Claude doesn't follow instructions
Common causes:
1. Instructions too verbose
– Keep instructions concise
– Use bullet points and numbered lists
– Move detailed reference to separate files
2. Instructions buried
– Put critical instructions at the top
– Use ## Important or ## Critical headers
– Repeat key points if needed
3. Ambiguous language
# Bad
Make sure to validate things properly
# Good
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past
Advanced technique: For critical validations, consider bundling a script
that performs the checks programmatically rather than relying on language
instructions. Code is deterministic; language interpretation isn't. See the Office
skills for examples of this pattern.
4. Model "laziness" Add explicit encouragement:
## Performance Notes
- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps
Note: Adding this to user prompts is more effective than in SKILL.md
26
Large context issues
Symptom: Skill seems slow or responses degraded
Causes:
•
Skill content too large
•
Too many skills enabled simultaneously
•
All content loaded instead of progressive disclosure
Solutions:
1. Optimize SKILL.md size
– Move detailed docs to references/
– Link to references instead of inline
– Keep SKILL.md under 5,000 words
2. Reduce enabled skills
– Evaluate if you have more than 20 - 50 skills enabled simultaneously
– Recommend selective enablement
– Consider skill "packs" for related capabilities
27
Chapter 6
Resources and
references
28
Chapter 6
Resources and references
If you're building your first skill, start with the Best Practices Guide, then
reference the API docs as needed.
Official Documentation
Anthropic Resources:
Best Practices Guide
•
•
•
•
Skills Documentation
API Reference
MCP Documentation
Blog Posts:
•
Introducing Agent Skills
•
Engineering Blog: Equipping Agents for the Real World
•
Skills Explained
•
How to Create Skills for Claude
•
•
Building Skills for Claude Code
Improving Frontend Design through Skills
Example skills
Public skills repository:
•
GitHub: anthropics/skills
•
Contains Anthropic-created skills you can customize
Tools and Utilities
skill-creator skill:
•
•
•
•
Built into Claude.ai and available for Claude Code
Can generate skills from descriptions
Reviews and provides recommendations
Use: "Help me build a skill using skill-creator"
Validation:
•
•
skill-creator can assess your skills
Ask: "Review this skill and suggest improvements"
Getting Support
For Technical Questions:
•
General questions: Community forums at the Claude Developers Discord
For Bug Reports:
•
•
GitHub Issues: anthropics/skills/issues
Include: Skill name, error message, steps to reproduce
29
Reference A: Quick
checklist
Use this checklist to validate your skill before and after upload. If you want
a faster start, use the skill-creator skill to generate your first draft, then run
through this list to make sure you haven't missed anything.
Before upload
Tested triggering on obvious tasks
Tested triggering on paraphrased requests
Verified doesn't trigger on unrelated topics
Functional tests pass
Tool integration works (if applicable)
Compressed as .zip file
Before you start
Identified 2-3 concrete use cases
Tools identified (built-in or MCP)
Reviewed this guide and example skills
Planned folder structure
After upload
Test in real conversations
Monitor for under/over-triggering
Collect user feedback
Iterate on description and instructions
Update version in metadata
During development
Folder named in kebab-case
SKILL.md file exists (exact spelling)
YAML frontmatter has --- delimiters
name field: kebab-case, no spaces, no capitals
description includes WHAT and WHEN
No XML tags (< >) anywhere
Instructions are clear and actionable
Error handling included
Examples provided
References clearly linked
30
Reference B: YAML
frontmatter
Security notes
Required fields
Allowed:
•
•
•
Any standard YAML types (strings, numbers, booleans, lists, objects)
Custom metadata fields
Long descriptions (up to 1024 characters)
---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific
trigger phrases.
---
Forbidden:
•
•
•
XML angle brackets (< >) - security restriction
Code execution in YAML (uses safe YAML parsing)
Skills named with "claude" or "anthropic" prefix (reserved)
All optional fields
name: skill-name
description: [required description]
license: MIT # Optional: License for open-source
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Optional:
Restrict tool access
metadata: # Optional: Custom fields
author: Company Name
version: 1.0.0
mcp-server: server-name
category: productivity
tags: [project-management, automation]
documentation: https://example.com/docs
support: support@example.com
31
Reference C: Complete skill
examples
For full, production-ready skills demonstrating the patterns in this guide:
Document Skills - PDF, DOCX, PPTX, XLSX creation
•
•
Example Skills - Various workflow patterns
•
Partner Skills Directory - View skills from various partners such as Asana,
Atlassian, Canva, Figma, Sentry, Zapier, and more
These repositories stay up-to-date and include additional examples beyond
what's covered here. Clone them, modify them for your use case, and use them as
templates.
32
claude.ai

[coderabbitai]

Coding Plan

Summary

• Create a new skill-design-patterns.md reference file to document the 4 applicable design patterns (excluding Multi-MCP since it's not used in this codebase) as a dedicated progressive-disclosure resource
• Enhance existing CSO guidance with negative triggers and the debugging tip for testing skill activation
• Add practical constraints (word limits, file conventions) and iteration/debugging guidance directly to the main skill documentation
• Expand testing documentation with the PDF's three-category testing framework (Triggering, Functional, Performance) integrated with the existing TDD methodology

Design Choices

Design Choice 1: Should Multi-MCP coordination pattern be included?

Options Considered:

1. Include Multi-MCP guidance for future-proofing and completeness
2. Exclude Multi-MCP guidance since it's not applicable to this codebase

Chosen Option: 2

Rationale: Exclude Multi-MCP guidance since the skill should focus on immediately actionable patterns that align with how skills are actually used in this system.

Design Choice 2: Where should design patterns content be placed?

Options Considered:

1. Add all content to existing anthropic-best-practices.md (already 1,150 lines)
2. Create a new skill-design-patterns.md reference file for patterns
3. Integrate patterns directly into SKILL.md

Chosen Option: 2

Rationale: Create dedicated skill-design-patterns.md for design patterns. This follows the skill's own progressive disclosure recommendation (heavy reference >100 lines goes to separate files) and keeps related architectural guidance together.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add Design Patterns Reference

This phase introduces the formalized design patterns from the PDF as a dedicated reference document, then integrates references into the main skill documentation.

Task 1: Create Design Patterns Reference File

Create a new reference document that formalizes the 4 applicable design patterns from the PDF.

• Create skills/writing-skills/skill-design-patterns.md containing the design patterns framework
• Document Sequential Workflow Orchestration pattern: ordered steps, dependencies between steps, per-step validation, rollback guidance
• Document Iterative Refinement Loops pattern: draft → validate → fix → re-validate cycle with explicit stop criteria
• Document Context-Aware Tool Selection pattern: decision trees for tool choice, fallback strategies, transparency about selection rationale
• Document Domain-Specific Intelligence pattern: embedding domain rules before actions, maintaining audit trails, governance considerations
• Include brief examples or references to existing skills that demonstrate each pattern (e.g., systematic-debugging uses iterative refinement, executing-plans uses sequential orchestration)
• Add guidance on when to apply each pattern and how patterns can be composed together

Task 2: Reference Design Patterns from Main Skill

Update the main skill to incorporate the new patterns reference.

• Update skills/writing-skills/SKILL.md to add a "Design Patterns" section that introduces the concept and references the new file
• Position this section logically within the existing structure (likely after "Skill Types" and before "Directory Structure")
• Keep the reference brief in SKILL.md, following the progressive disclosure pattern

🤖 Prompt for AI agents

Introduce formalized design patterns from Anthropic's guide as a dedicated
reference document and integrate it into the main skill documentation.

**Task 1: Create Design Patterns Reference File**
- Create new file `skills/writing-skills/skill-design-patterns.md`
- Document the 4 applicable design patterns:
- **Sequential Workflow Orchestration**: ordered steps, dependencies between
steps, per-step validation, rollback guidance
- **Iterative Refinement Loops**: draft → validate → fix → re-validate cycle
with explicit stop criteria
- **Context-Aware Tool Selection**: decision trees for tool choice, fallback
strategies, transparency about selection rationale
- **Domain-Specific Intelligence**: embedding domain rules before actions,
maintaining audit trails, governance considerations
- For each pattern, include:
- Brief examples or references to existing skills (e.g., systematic-debugging
uses iterative refinement, executing-plans uses sequential orchestration)
  - Guidance on when to apply the pattern
  - How patterns can be composed together

**Task 2: Reference Design Patterns from Main Skill**
- Update `skills/writing-skills/SKILL.md`
- Add new "Design Patterns" section that introduces the concept and references
the new file
- Position after "Skill Types" and before "Directory Structure"
- Keep the reference brief following progressive disclosure pattern

Phase 2: Enhance Existing Skill Guidance

This phase integrates the PDF's recommendations on descriptions, structure, and practical constraints into the existing documentation.

Task 1: Add Negative Triggers to CSO Guidance

Enhance the Claude Search Optimization section with negative trigger patterns.

• Update the CSO section in skills/writing-skills/SKILL.md to include guidance on negative triggers
• Add instruction to include explicit "Do NOT use for..." statements in descriptions when skills could over-trigger
• Provide examples showing good negative trigger usage (e.g., "Use when writing new skills. Do NOT use for project-specific documentation or one-off instructions.")

Task 2: Add Recommended SKILL.md Layout Structure

Document the PDF's recommended layout for skill body content.

• Add a section or expand existing "SKILL.md Structure" section in skills/writing-skills/SKILL.md with the recommended layout: Instructions → Step-by-step Workflow → Examples → Troubleshooting
• Explain the purpose of each section and when each is needed
• Note this is a recommended structure, not mandatory, for flexibility

Task 3: Add Practical Constraints and Limits

Document practical guidance on size limits and file conventions.

• Update skills/writing-skills/SKILL.md or anthropic-best-practices.md to include guidance on keeping SKILL.md under ~5,000 words
• Add warning to avoid placing a README.md inside skill folders (can cause confusion with SKILL.md)
• Document the guidance about evaluating skill count when 20-50+ skills are enabled simultaneously
• Include the debugging tip: Ask Claude "When would you use the [skill]?" to test triggering

Task 4: Add Iteration and Debugging Guidance

Document how to diagnose and fix common skill issues.

• Add an "Iteration & Debugging" section to skills/writing-skills/SKILL.md covering common issues and fixes
• Document fix for under-triggering: Enrich description with more keywords, synonyms, and trigger phrases users would actually say
• Document fix for over-triggering: Add negative triggers, narrow scope explicitly
• Document fix for execution issues: Tighten instructions, add explicit error handling, add performance notes
• Include the tip that performance notes can be more effective in user prompts than in SKILL.md itself

🤖 Prompt for AI agents

Integrate Anthropic PDF recommendations on descriptions, structure, and
practical constraints into existing skill documentation.

**Task 1: Add Negative Triggers to CSO Guidance**
- Update CSO section in `skills/writing-skills/SKILL.md`
- Add guidance on **negative triggers**
- Include instruction to use explicit "Do NOT use for..." statements when skills
could over-trigger
- Provide examples of good negative trigger usage (e.g., "Use when writing new
skills. Do NOT use for project-specific documentation or one-off instructions.")

**Task 2: Add Recommended SKILL.md Layout Structure**
- Add or expand "SKILL.md Structure" section in `skills/writing-skills/SKILL.md`
- Document recommended layout: **Instructions → Step-by-step Workflow → Examples
→ Troubleshooting**
- Explain purpose of each section and when needed
- Note this is recommended, not mandatory

**Task 3: Add Practical Constraints and Limits**
- Update `skills/writing-skills/SKILL.md` or `anthropic-best-practices.md`
- Add guidance on keeping SKILL.md under ~5,000 words
- Add warning about avoiding `README.md` inside skill folders (confusion with
SKILL.md)
- Document guidance about evaluating skill count when 20-50+ skills enabled
simultaneously
- Include debugging tip: Ask Claude "When would you use the [skill]?" to test
triggering

**Task 4: Add Iteration and Debugging Guidance**
- Add "Iteration & Debugging" section to `skills/writing-skills/SKILL.md`
- Document fixes for common issues:
- **Under-triggering**: Enrich description with more keywords, synonyms, and
trigger phrases users would actually say
  - **Over-triggering**: Add negative triggers, narrow scope explicitly
- **Execution issues**: Tighten instructions, add explicit error handling, add
performance notes
- Include tip that performance notes can be more effective in user prompts than
in SKILL.md itself

Phase 3: Expand Testing Documentation

This phase enhances the testing methodology with the structured testing categories from the PDF.

Task 1: Add Structured Testing Approaches

Expand testing documentation with the three testing categories from the PDF.

• Update skills/writing-skills/testing-skills-with-subagents.md to incorporate the PDF's testing framework
• Add Triggering Tests section: Test that skill triggers on obvious requests, paraphrased requests, and does NOT trigger on unrelated requests
• Add Functional Tests section: Verify correct outputs, successful tool/API calls, proper error handling, edge cases
• Add Performance Comparison section: Compare against baseline (no skill) measuring message count, tool calls, failure rate, token usage
• Integrate these with the existing RED-GREEN-REFACTOR methodology, showing how they complement pressure scenario testing

Task 2: Add Testing Approaches Summary to Main Skill

Reference the expanded testing approaches from the main skill file.

• Update the "Testing All Skill Types" section in skills/writing-skills/SKILL.md to briefly mention the three testing categories
• Maintain reference to the detailed methodology in testing-skills-with-subagents.md
• Ensure the connection between pressure scenarios (existing) and structured test categories (new) is clear

🤖 Prompt for AI agents

Enhance testing methodology with structured testing categories from Anthropic's
PDF, integrating with existing TDD approach.

**Task 1: Add Structured Testing Approaches**
- Update `skills/writing-skills/testing-skills-with-subagents.md` to incorporate
PDF's testing framework
- Add three testing categories:
- **Triggering Tests**: Test that skill triggers on obvious requests,
paraphrased requests, and does NOT trigger on unrelated requests
- **Functional Tests**: Verify correct outputs, successful tool/API calls,
proper error handling, edge cases
- **Performance Comparison**: Compare against baseline (no skill) measuring
message count, tool calls, failure rate, token usage
- Integrate with existing RED-GREEN-REFACTOR methodology
- Show how these categories complement pressure scenario testing

**Task 2: Add Testing Approaches Summary to Main Skill**
- Update "Testing All Skill Types" section in `skills/writing-skills/SKILL.md`
- Briefly mention the three testing categories
- Maintain reference to detailed methodology in
`testing-skills-with-subagents.md`
- Ensure clear connection between pressure scenarios (existing) and structured
test categories (new)

Research

The skills/writing-skills/ directory contains a comprehensive skill-authoring framework built around TDD principles. The main SKILL.md (655 lines) covers the core methodology, while anthropic-best-practices.md (1,150 lines) provides existing Anthropic guidance on skill structure, progressive disclosure, and evaluation. Supporting files include testing methodology (testing-skills-with-subagents.md), persuasion principles, and graphviz conventions. The exploration revealed that while workflows, progressive disclosure, and testing basics are covered, the PDF introduces formalized design patterns, structured testing categories, negative triggers for descriptions, and iteration/debugging guidance that are not yet documented.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Introduce formalized design patterns from Anthropic's guide as a dedicated
reference document and integrate it into the main skill documentation.

**Task 1: Create Design Patterns Reference File**
- Create new file `skills/writing-skills/skill-design-patterns.md`
- Document the 4 applicable design patterns:
- **Sequential Workflow Orchestration**: ordered steps, dependencies between
steps, per-step validation, rollback guidance
- **Iterative Refinement Loops**: draft → validate → fix → re-validate cycle
with explicit stop criteria
- **Context-Aware Tool Selection**: decision trees for tool choice, fallback
strategies, transparency about selection rationale
- **Domain-Specific Intelligence**: embedding domain rules before actions,
maintaining audit trails, governance considerations
- For each pattern, include:
- Brief examples or references to existing skills (e.g., systematic-debugging
uses iterative refinement, executing-plans uses sequential orchestration)
  - Guidance on when to apply the pattern
  - How patterns can be composed together

**Task 2: Reference Design Patterns from Main Skill**
- Update `skills/writing-skills/SKILL.md`
- Add new "Design Patterns" section that introduces the concept and references
the new file
- Position after "Skill Types" and before "Directory Structure"
- Keep the reference brief following progressive disclosure pattern
===============================================================================

Task: 2

Integrate Anthropic PDF recommendations on descriptions, structure, and
practical constraints into existing skill documentation.

**Task 1: Add Negative Triggers to CSO Guidance**
- Update CSO section in `skills/writing-skills/SKILL.md`
- Add guidance on **negative triggers**
- Include instruction to use explicit "Do NOT use for..." statements when skills
could over-trigger
- Provide examples of good negative trigger usage (e.g., "Use when writing new
skills. Do NOT use for project-specific documentation or one-off instructions.")

**Task 2: Add Recommended SKILL.md Layout Structure**
- Add or expand "SKILL.md Structure" section in `skills/writing-skills/SKILL.md`
- Document recommended layout: **Instructions → Step-by-step Workflow → Examples
→ Troubleshooting**
- Explain purpose of each section and when needed
- Note this is recommended, not mandatory

**Task 3: Add Practical Constraints and Limits**
- Update `skills/writing-skills/SKILL.md` or `anthropic-best-practices.md`
- Add guidance on keeping SKILL.md under ~5,000 words
- Add warning about avoiding `README.md` inside skill folders (confusion with
SKILL.md)
- Document guidance about evaluating skill count when 20-50+ skills enabled
simultaneously
- Include debugging tip: Ask Claude "When would you use the [skill]?" to test
triggering

**Task 4: Add Iteration and Debugging Guidance**
- Add "Iteration & Debugging" section to `skills/writing-skills/SKILL.md`
- Document fixes for common issues:
- **Under-triggering**: Enrich description with more keywords, synonyms, and
trigger phrases users would actually say
  - **Over-triggering**: Add negative triggers, narrow scope explicitly
- **Execution issues**: Tighten instructions, add explicit error handling, add
performance notes
- Include tip that performance notes can be more effective in user prompts than
in SKILL.md itself
===============================================================================

Task: 3

Enhance testing methodology with structured testing categories from Anthropic's
PDF, integrating with existing TDD approach.

**Task 1: Add Structured Testing Approaches**
- Update `skills/writing-skills/testing-skills-with-subagents.md` to incorporate
PDF's testing framework
- Add three testing categories:
- **Triggering Tests**: Test that skill triggers on obvious requests,
paraphrased requests, and does NOT trigger on unrelated requests
- **Functional Tests**: Verify correct outputs, successful tool/API calls,
proper error handling, edge cases
- **Performance Comparison**: Compare against baseline (no skill) measuring
message count, tool calls, failure rate, token usage
- Integrate with existing RED-GREEN-REFACTOR methodology
- Show how these categories complement pressure scenario testing

**Task 2: Add Testing Approaches Summary to Main Skill**
- Update "Testing All Skill Types" section in `skills/writing-skills/SKILL.md`
- Briefly mention the three testing categories
- Maintain reference to detailed methodology in
`testing-skills-with-subagents.md`
- Ensure clear connection between pressure scenarios (existing) and structured
test categories (new)

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[obra]

Verified by Claude Code: skills/writing-skills/anthropic-best-practices.md and skills/writing-skills/references/ exist on main and reflect Anthropic's official skill authoring best practices, addressing this request.

— Claude Opus 4.7, Claude Code 2.1.112