AI Skill Report Card
Crafting Claude Skills
YAML--- name: crafting-claude-skills description: Creates and improves Claude Code agent skills using expert patterns and best practices. Use when developing new skills or refining existing ones. --- # Crafting Claude Skills
Quick Start15 / 15
YAML--- name: analyzing-code-quality description: Analyzes code for maintainability, performance, and best practices. Use when reviewing codebases or preparing code for production. --- # Analyzing Code Quality
Recommendation▾
Add specific templates or frameworks section with copy-pasteable skill scaffolds for common patterns
Quick Start15 / 15
Python# Example analysis output issues = { 'critical': ['No error handling in main function'], 'style': ['Inconsistent naming: mixedCase vs snake_case'], 'performance': ['O(n²) loop could be optimized'] }
Recommendation▾
Include edge cases like handling skills that are too similar or skills that should be merged
Workflow13 / 15
- Parse code structure and imports
- Check for common antipatterns
- Evaluate performance bottlenecks
- Generate prioritized recommendations
Recommendation▾
Provide validation checklist with specific criteria for evaluating skill quality before publishing
Workflow13 / 15
Progress:
- Define skill purpose and trigger phrases
- Create YAML frontmatter with gerund name
- Write immediate Quick Start example
- Structure clear workflow steps
- Add concrete input/output examples
- Include actionable best practices
- List common pitfalls to avoid
- Validate skill length (~500 lines max)
Examples18 / 20
Example 1: Data Processing Skill Input: "I need to clean CSV files with missing data" Output:
YAMLname: cleaning-csv-data description: Cleans and validates CSV files with missing or malformed data. Use when preprocessing datasets for analysis.
Example 2: Documentation Skill Input: "I write technical documentation for APIs" Output:
YAMLname: writing-api-documentation description: Creates comprehensive API documentation with examples and best practices. Use when documenting REST APIs or SDKs.
Best Practices
Naming Convention:
- Always use gerund form:
processing-imagesnotimage-processor - Kebab-case only:
analyzing-performancenotanalyzing_performance - Be specific:
optimizing-sql-queriesnotoptimizing-databases
Description Formula:
- Action + Object + Context: "Analyzes SQL queries for performance bottlenecks"
- Always include trigger: "Use when optimizing database performance"
- Third person only: "Creates..." not "Create..."
Structure Hierarchy:
- Quick Start - Code/concrete example first
- Workflow - Numbered steps with checkboxes for complex flows
- Examples - Always input/output pairs
- Best Practices - Actionable guidelines
- Common Pitfalls - What NOT to do
Content Guidelines:
- Default to one recommended approach, not multiple options
- Assume Claude knows basics (no explaining what JSON is)
- Include realistic data in examples
- Keep workflows to 5-8 steps maximum
- Use code blocks for any technical output
Quality Checks:
- Can someone use this immediately? (Quick Start test)
- Are examples copy-pasteable? (Practicality test)
- Does it solve a specific problem? (Scope test)
- Is it under 500 lines? (Brevity test)
Common Pitfalls
Naming Mistakes:
- Using noun forms:
code-analyzer→analyzing-code - Mixed cases:
analyzeCode→analyzing-code - Too generic:
helper→formatting-json-responses
Description Errors:
- First/second person: "You can analyze" → "Analyzes"
- Missing triggers: "Analyzes code" → "Analyzes code for bugs. Use when reviewing pull requests"
- Vague scope: "Helps with data" → "Cleans CSV files with missing values"
Structure Issues:
- Starting with explanation instead of example
- Multiple workflow options instead of one clear path
- Abstract examples instead of concrete input/output
- Missing checklists for complex multi-step processes
Content Problems:
- Over-explaining basic concepts Claude already knows
- Offering too many alternatives instead of recommended defaults
- Examples that can't be copy-pasted and used immediately
- Workflows longer than 8 steps without breaking into sub-skills