Skill Creator Guide

A meta-skill for authoring high-quality Claude Code skills with structured prompts, proper formatting, and effective instruction design following best practices for AI skill engineering.

When to Use

Choose Skill Creator Guide when:

• Writing new Claude Code skills that follow consistent formatting and quality standards
• Converting existing workflows into reusable Claude Code skill files
• Optimizing existing skills for clarity, specificity, and reliability
• Training team members on effective skill authoring practices

Consider alternatives when:

• Using existing skills — execute them directly without modification
• Building MCP servers — use MCP SDK documentation
• Writing general documentation — use standard documentation tools

Quick Start

Copy
# Skill File Structure (.md in .claude/ directory)

---
description: One-line description of what this skill does
---

# Skill Title

Clear description of the skill's purpose and what it produces.

## When to Use
- Specific scenario 1
- Specific scenario 2

## Instructions

### Step 1: Gather Information
- Read the relevant files: {list specific files}
- Check for existing patterns: {what to look for}

### Step 2: Implement
- Create/modify files following these rules:
  - Rule 1 with specific example
  - Rule 2 with specific example

### Step 3: Verify
- Run tests: `npm test`
- Check for regressions: `npm run lint`

## Examples

### Input

User request: "Add a login page"

### Expected Output

Files created:

• src/pages/login.tsx
• src/components/LoginForm.tsx

## Constraints
- Never modify files outside src/
- Always use TypeScript
- Follow existing naming conventions

Copy
// Skill quality assessment tool
interface SkillAssessment {
  clarity: number;      // 1-10: How clear are the instructions?
  specificity: number;  // 1-10: How specific vs vague?
  completeness: number; // 1-10: Does it cover edge cases?
  testability: number;  // 1-10: Can output be verified?
  reusability: number;  // 1-10: How broadly applicable?
}

function assessSkill(skillContent: string): SkillAssessment {
  const sections = skillContent.split(/^## /m);
  const hasWhenToUse = skillContent.includes('## When to Use');
  const hasInstructions = skillContent.includes('## Instructions');
  const hasExamples = skillContent.includes('## Example');
  const hasConstraints = skillContent.includes('## Constraint');
  const hasSteps = (skillContent.match(/### Step/g) || []).length;
  const hasCodeBlocks = (skillContent.match(/```/g) || []).length / 2;

  return {
    clarity: Math.min(10, sections.length + hasSteps * 2),
    specificity: Math.min(10, hasCodeBlocks * 2 + (hasConstraints ? 3 : 0)),
    completeness: Math.min(10,
      (hasWhenToUse ? 2 : 0) + (hasInstructions ? 3 : 0) +
      (hasExamples ? 3 : 0) + (hasConstraints ? 2 : 0)
    ),
    testability: hasExamples ? 8 : 4,
    reusability: Math.min(10, sections.length + (hasWhenToUse ? 3 : 0))
  };
}

Core Concepts

Skill Quality Dimensions

Dimension	What It Measures	How to Improve
Clarity	Can the AI follow the instructions unambiguously?	Use numbered steps, avoid jargon
Specificity	Are instructions precise about what to do?	Include file paths, code patterns
Completeness	Are edge cases and error handling covered?	Add constraints and fallback instructions
Testability	Can the output be verified?	Include expected output examples
Reusability	Does the skill work across projects?	Parameterize project-specific values

Instruction Writing Patterns

Copy
## Good: Specific, actionable instruction
### Step 1: Create the Component
Create `src/components/{ComponentName}.tsx` with:
- Export a named function component (not default export)
- Accept props interface `{ComponentName}Props`
- Use `className` prop for styling
- Include `data-testid="{component-name}"` on the root element

## Bad: Vague, open to interpretation
### Step 1: Create the Component
Make a React component for the feature.

Configuration

Option	Description	Default
skill_directory	Directory for skill files	".claude/"
format	Skill file format	"markdown"
require_examples	Require example section	true
require_constraints	Require constraints section	true
max_skill_length	Maximum skill file length (lines)	200
naming_convention	File naming pattern	"kebab-case.md"
include_metadata	Include frontmatter metadata	true
validation	Validate skill structure	true

Best Practices

1. Write instructions as imperative commands ("Create a file at...", "Add the following code...") rather than descriptions ("The file should contain...") because imperative instructions are unambiguous and directly executable
2. Include concrete code examples for every pattern you want the AI to follow — showing an example of the desired output format is more effective than describing it in words
3. Specify constraints explicitly listing what the skill should NOT do alongside what it should do — constraints prevent the AI from over-engineering, modifying wrong files, or adding unwanted features
4. Use conditional sections for varying scenarios ("If the project uses TypeScript...", "If no existing tests directory...") to handle different project configurations without creating separate skills
5. Test skills with different inputs to verify they produce consistent, correct output across various parameter values and project states before sharing with the team

Common Issues

AI not following instructions precisely: Vague or ambiguous instructions lead to inconsistent output. Be more specific: instead of "add proper error handling," write "wrap the async call in try/catch, log the error with console.error, and return a 500 response with { error: 'Internal server error' }."

Skill too rigid for different projects: Skills that hardcode file paths, framework conventions, or naming patterns only work in one project. Parameterize project-specific values, include conditional instructions for different setups, and focus on the pattern rather than the implementation details.

Skill instructions conflicting with project conventions: A skill that prescribes one naming convention may conflict with an existing project's patterns. Always include "check existing patterns in the project" as an early step, and phrase instructions as defaults that defer to established project conventions.