Menu
Guide for creating effective skills. Use when creating a new skill, updating an existing skill, or verifying skills work before deployment. Covers skill structure, creation process, testing methodology, and packaging.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | skill-creator |
| description | Guide for creating effective skills. Use when creating a new skill, updating an existing skill, or verifying skills work before deployment. Covers skill structure, creation process, testing methodology, and packaging. |
Create effective, tested skills that extend Claude's capabilities with specialized knowledge, workflows, and tools.
Skills are modular packages that provide:
The context window is a public good. Only add context Claude doesn't already have. Challenge each piece: "Does Claude really need this?" Prefer concise examples over verbose explanations.
Three-level loading to manage context efficiently:
skill-name/
โโโ SKILL.md # Required: frontmatter + instructions
โโโ scripts/ # Optional: executable code (Python/Bash)
โโโ references/ # Optional: docs loaded into context as needed
โโโ assets/ # Optional: files used in output (templates, icons)
Only name and description are required. The description is the primary trigger โ it determines when the skill loads.
---
name: my-skill
description: Use when [specific triggering conditions and symptoms]
---
Description rules:
Do NOT include: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or auxiliary docs about the creation process.
Ask the user:
For each example, identify what scripts, references, and assets would help when executing these workflows repeatedly.
Create the skill directory with a SKILL.md containing frontmatter (name + description) and the appropriate resource subdirectories (scripts/, references/, assets/) as needed.
Consult these guides based on your needs:
Start with reusable resources, then write SKILL.md. Use imperative/infinitive form.
Verify the skill has valid frontmatter (name + description, kebab-case name, under 1024 chars), then package with zip -r skill-name.skill skill-name/ if distributing.
Skill creation IS Test-Driven Development applied to process documentation.
Follow RED-GREEN-REFACTOR:
RED โ Baseline test (before writing/editing the skill):
GREEN โ Write minimal skill:
REFACTOR โ Close loopholes:
The Iron Law: No skill without a failing test first. This applies to new skills AND edits.
For the complete testing methodology (pressure scenarios, pressure types, plugging holes, meta-testing), see references/testing-skills-with-subagents.md.
For psychology of persuasion techniques in discipline-enforcing skills, see references/persuasion-principles.md.
Future Claude needs to FIND your skill:
condition-based-waiting not async-test-helpers)| Type | Examples | Test With |
|---|---|---|
| Discipline (rules) | TDD, verification | Pressure scenarios, rationalization resistance |
| Technique (how-to) | condition-based-waiting | Application + edge cases |
| Pattern (mental model) | flatten-with-flags | Recognition + counter-examples |
| Reference (docs/APIs) | API guides | Retrieval + application accuracy |
Pattern 1: High-level guide linking to references for advanced features Pattern 2: Domain-specific organization (only load relevant domain file) Pattern 3: Conditional details (basic inline, advanced linked)
Keep references one level deep from SKILL.md. For files >100 lines, include a table of contents.
Use ONLY for non-obvious decisions, process loops, or A-vs-B choices. Never for reference material, code examples, or linear instructions.
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework with built-in backward tracing for deep-stack failures, ensuring root-cause understanding before implementation
Turn the current session into a coordination thread that routes per-branch implementation work to durable, reusable child agents. Use when the user says 'orchestrator on', wants this session to act as chief-of-staff across branches, or asks to route work without implementing locally.
Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
Adversarial questioning and collaborative shaping in one skill. Two modes: stress-test (challenge a plan/design until gaps surface) and shape (iterate on requirements and solution options until alignment). Use when user says 'grill me', 'stress-test this', 'challenge this plan', 'shape this', 'let's explore options', or wants to pressure-test any design before committing.
Compact the current session into a handoff document for another agent or future session to pick up. Captures mission, repo state, role, scope, locked decisions, dispatch sequence, and a pickup checklist. Studio-aware. Use when pausing work, ending a session, switching contexts, or preparing for a fresh agent to continue.
Initialize a new project with PROJECT.md + ROADMAP.md in .project/, set up jira and studio, and route to the first sprint. Use when starting a new project, onboarding a new codebase, or setting up workflow infrastructure for the first time.