gh-tenequm-claude-plugins-skill-factory/skills/skill/references/anthropic-best-practices.md

Anthropic Best Practices for Claude Skills

Extracted from official Anthropic documentation with attribution.

Core Principles

1. Conciseness - Keep SKILL.md under 500 lines
2. Progressive Disclosure - Use reference files for details
3. Specific Descriptions - Clear when_to_use in frontmatter
4. Concrete Examples - Real code, not placeholders
5. Assume Intelligence - Trust Claude to understand

SKILL.md Structure

---
name: skill-name
description: Specific description of what this does and when to use it
---

# Skill Name

## Overview
Brief explanation of core purpose

## When to Use
Clear triggers and use cases

## Quick Reference
Table or bullets for common operations

## Examples
Concrete, runnable code

## Common Mistakes
What goes wrong + fixes

Quality Scoring (10 points total)

1. Description Quality (2.0 points)

• ✅ Specific, not vague
• ✅ Includes what the skill does
• ✅ Includes when to use it
• ✅ Written in third person
• ✅ Under 1024 characters
• ❌ No "helps with", "tool for" vagueness

2. Name Convention (0.5 points)

• ✅ lowercase-with-hyphens
• ✅ Descriptive (not "helper", "utils")
• ✅ Gerund form preferred (-ing)
• ✅ Under 64 characters

3. Conciseness (1.5 points)

• ✅ <300 lines = 1.5 points
• ✅ <500 lines = 1.0 points
• ⚠️ 500-800 lines = 0.5 points
• ❌ >800 lines = 0.0 points

4. Progressive Disclosure (1.0 points)

• ✅ Main SKILL.md is overview/TOC
• ✅ Details in reference files
• ✅ No deeply nested references (max 1 level)

5. Examples & Workflows (1.0 points)

• ✅ Concrete code examples
• ✅ Input/output pairs
• ✅ Real patterns, not placeholders
• ❌ No "template" or "fill-in-blank"

6. Degree of Freedom (0.5 points)

• ✅ High freedom for flexible tasks (text instructions)
• ✅ Low freedom for fragile tasks (exact scripts)

7. Dependencies (0.5 points)

• ✅ All dependencies listed
• ✅ Installation instructions
• ✅ Verified available

8. Structure (1.0 points)

• ✅ Clear section headings
• ✅ Logical flow
• ✅ Consistent formatting
• ✅ Unix paths (forward slashes)

9. Error Handling (0.5 points)

For skills with scripts:

• ✅ Scripts handle errors
• ✅ Clear error messages
• ✅ Validation loops

10. Anti-Patterns to Avoid (1.0 points)

• ❌ Time-sensitive information
• ❌ Inconsistent terminology
• ❌ Windows-style paths ()
• ❌ Too many options without guidance
• ❌ Deeply nested references

11. Testing (0.5 points)

• ✅ Evidence of testing
• ✅ Evaluation examples
• ✅ Success criteria

Common Issues & Fixes

Issue: Description Too Vague

❌ Bad: "Helps with documents" ✅ Good: "Analyze Excel spreadsheets, create pivot tables, generate charts. Use when working with .xlsx files or tabular data."

Issue: Too Long

❌ Bad: 800-line SKILL.md with everything inline ✅ Good: 300-line overview + 3 reference files

Issue: Abstract Examples

❌ Bad: function doSomething() { /* your code here */ } ✅ Good: Complete, runnable examples from real use cases

Issue: No When-to-Use

❌ Bad: description: "React development tool" ✅ Good: description: "Build React applications with hooks, routing, and state management. Use when creating React projects, need component patterns, or debugging React-specific issues."

File Organization

skill-name/
├── SKILL.md                 # <500 lines overview
├── references/              # Detailed docs
│   ├── api-reference.md
│   ├── advanced-usage.md
│   └── troubleshooting.md
├── scripts/                 # Executable tools
│   └── helper-script.sh
└── examples/               # Complete examples
    └── example-project.md

Frontmatter Best Practices

---
name: processing-documents
description: Extract text from PDFs, analyze Word docs, convert formats. Use when working with PDF, DOCX, or document conversion tasks.
dependencies:
  - pypdf2
  - python-docx
---

Progressive Disclosure Pattern

Main SKILL.md (200 lines):

• Overview
• Quick reference table
• Common workflows
• Links to references

References (unlimited):

• Detailed API docs
• Advanced patterns
• Troubleshooting
• Extended examples

Quality Tiers

• Excellent (8.0-10.0): Production-ready, follows all best practices
• Good (6.0-7.9): Usable, minor improvements needed
• Fair (4.0-5.9): Needs review, several issues
• Poor (0.0-3.9): Significant problems, not recommended

Source

Based on Anthropic Skills Documentation

• skill-creator/SKILL.md
• Official best practices guide

Quick Validation Checklist

Before deploying any skill:

• Description specific and under 1024 chars?
• Name follows lowercase-hyphen convention?
• SKILL.md under 500 lines (or uses progressive disclosure)?
• Has 3+ concrete code examples?
• No time-sensitive information?
• Dependencies documented?
• Unix-style paths?
• Tested with real queries?