Skill Creation Guide Engine

A comprehensive skill for designing, building, testing, and publishing Claude Code skills. Covers skill anatomy, prompt engineering for skill instructions, configuration schemas, and best practices for creating modular, reusable skills that extend Claude's capabilities.

When to Use This Skill

Choose this skill when:

• Creating a new Claude Code skill from scratch with proper structure
• Designing skill instructions that produce consistent, high-quality outputs
• Building configurable skills with parameter schemas and defaults
• Testing and iterating on skill behavior with edge cases
• Publishing skills for team or community use

Consider alternatives when:

• Building MCP servers → use an MCP development skill
• Creating Claude Code hooks → use a hooks development skill
• Writing Claude Code commands → use a command development skill
• Configuring Claude Code settings → use a settings skill

Quick Start

Copy
# Skill file structure
.claude/skills/
├── my-skill.md           # Main skill definition
├── my-skill.config.json  # Optional: configuration schema
└── examples/
    └── usage.md          # Optional: usage examples

# Minimal skill definition (.claude/skills/my-skill.md)
---
name: My Custom Skill
description: Brief description of what this skill does
---

# My Custom Skill

## Purpose
Describe what this skill accomplishes and when to use it.

## Instructions
Step-by-step instructions for Claude to follow when this skill is invoked.

## Rules
- Specific constraints and guidelines
- Output format requirements
- Error handling instructions

Core Concepts

Skill Anatomy

Section	Purpose	Required
Frontmatter	Name, description, metadata	Yes
Purpose	When and why to use this skill	Yes
Instructions	Step-by-step process	Yes
Rules	Constraints and guidelines	Recommended
Examples	Input/output demonstrations	Recommended
Configuration	Parameterized behavior	Optional
Error Handling	What to do when things go wrong	Optional

Effective Skill Instructions

Copy
# Writing Clear Skill Instructions

## Good: Specific, actionable, ordered
1. Read the target file using the Read tool
2. Identify all functions that match the pattern: `export function`
3. For each function, generate a JSDoc comment with:
   - @param tags for each parameter with types and descriptions
   - @returns tag with return type and description
   - @throws tag if the function can throw errors
4. Write the modified file using the Edit tool
5. Verify the changes by reading the file again

## Bad: Vague, ambiguous
- Add documentation to the code
- Make it well-documented
- Improve the code quality

Configuration Schema Pattern

Copy
{
  "name": "code-documenter",
  "description": "Generates documentation for code files",
  "parameters": {
    "style": {
      "type": "string",
      "enum": ["jsdoc", "tsdoc", "docstring"],
      "default": "jsdoc",
      "description": "Documentation style to use"
    },
    "includeExamples": {
      "type": "boolean",
      "default": true,
      "description": "Include usage examples in documentation"
    },
    "minFunctionLength": {
      "type": "number",
      "default": 3,
      "description": "Only document functions with this many lines or more"
    },
    "outputFormat": {
      "type": "string",
      "enum": ["inline", "separate-file", "readme"],
      "default": "inline",
      "description": "Where to place generated documentation"
    }
  }
}

Configuration

Parameter	Type	Default	Description
skillDirectory	string	'.claude/skills/'	Directory for skill definitions
configFormat	string	'json'	Config format: JSON or YAML
instructionStyle	string	'numbered'	Instruction format: numbered steps or prose
testingApproach	string	'example-based'	Testing: example-based or scenario-based
publishTarget	string	'local'	Publish: local, team, or community
versioningScheme	string	'semver'	Version scheme: semver or date-based

Best Practices

1. Write instructions as numbered steps, not prose paragraphs — Claude follows ordered steps more reliably than interpreting paragraph descriptions. Each step should be a single, verifiable action: read, analyze, generate, write, verify.

2. Include concrete input/output examples — Abstract rules are ambiguous. Showing Claude exactly what input looks like and what output should look like removes guesswork. Include 2-3 diverse examples covering common cases and edge cases.

3. Define explicit constraints with "always" and "never" rules — "Always include type annotations" and "Never modify existing function signatures" are clearer than "try to include types when possible." Explicit constraints produce consistent behavior.

4. Make skills modular and composable — A skill should do one thing well. A "full-stack feature builder" skill is too broad. Instead, create separate skills for "API endpoint generator," "database migration creator," and "React component scaffolder" that can be composed.

5. Test skills with adversarial inputs — Try edge cases: empty files, files with syntax errors, very large files, files in unexpected languages. A robust skill handles these gracefully rather than producing garbled output or failing silently.

Common Issues

Skill produces inconsistent output across invocations — Instructions are too vague or allow too much interpretation. Add specific format requirements: "Output exactly 3 bullet points," "Use this exact heading structure," "Return JSON with these exact keys."

Skill works for simple cases but fails on complex inputs — The instructions don't cover edge cases. Add explicit handling for: empty inputs, large files, nested structures, special characters, and multi-language codebases.

Skill conflicts with other active skills or settings — Skills can override each other when active simultaneously. Design skills to be self-contained and prefix any global settings they modify. Document conflicts in the skill's README.