# Skill Creator > 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. Use when this capability is needed. - Skill: `tomevault-io/skill-creator-130` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/skill-creator-130` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/skill-creator-130/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/skill-creator-130 --- # Skill Creator Create effective, tested skills that extend Claude's capabilities with specialized knowledge, workflows, and tools. ## About Skills Skills are modular packages that provide: 1. **Specialized workflows** - Multi-step procedures for specific domains 2. **Tool integrations** - Instructions for working with specific file formats or APIs 3. **Domain expertise** - Company-specific knowledge, schemas, business logic 4. **Bundled resources** - Scripts, references, and assets for complex tasks ## Core Principles ### Concise is Key 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. ### Set Appropriate Degrees of Freedom - **High freedom** (text instructions): Multiple approaches valid, context-dependent - **Medium freedom** (pseudocode/parameterized scripts): Preferred pattern exists, some variation OK - **Low freedom** (specific scripts): Fragile operations, consistency critical ### Progressive Disclosure Three-level loading to manage context efficiently: 1. **Metadata** (name + description) - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words, under 500 lines) 3. **Bundled resources** - As needed (unlimited, loaded on demand) ## Skill Anatomy ``` 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) ``` ### SKILL.md Frontmatter Only `name` and `description` are required. The description is the primary trigger — it determines when the skill loads. ```yaml --- name: my-skill description: Use when [specific triggering conditions and symptoms] --- ``` **Description rules:** - Start with "Use when..." — focus on triggering conditions - Include specific symptoms, situations, and contexts - Write in third person - **NEVER summarize the skill's workflow** in the description (Claude may follow the summary instead of reading the full skill) ### Bundled Resources - **scripts/**: Deterministic, reusable code. Token-efficient. Test by running them. - **references/**: Documentation Claude reads as needed. Keep SKILL.md lean by moving detailed info here. For large files (>10k words), include grep patterns in SKILL.md. - **assets/**: Files for output (templates, images, fonts). Not loaded into context. **Do NOT include:** README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or auxiliary docs about the creation process. ## Creation Process ### Step 1: Understand with Concrete Examples Ask the user: - What should the skill support? - Example usage scenarios? - What triggers should activate this skill? ### Step 2: Plan Reusable Contents For each example, identify what scripts, references, and assets would help when executing these workflows repeatedly. ### Step 3: Initialize the Skill Create the skill directory with a SKILL.md containing frontmatter (name + description) and the appropriate resource subdirectories (scripts/, references/, assets/) as needed. ### Step 4: Edit the Skill Consult these guides based on your needs: - **Multi-step processes**: See references/workflows.md - **Output formats/quality standards**: See references/output-patterns.md - **Official authoring guidance**: See references/anthropic-best-practices.md Start with reusable resources, then write SKILL.md. Use imperative/infinitive form. ### Step 5: Validate & Package 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. ### Step 6: Iterate with TDD **Skill creation IS Test-Driven Development applied to process documentation.** Follow RED-GREEN-REFACTOR: **RED — Baseline test (before writing/editing the skill):** 1. Create pressure scenarios (3+ combined pressures for discipline skills) 2. Run scenarios with a subagent WITHOUT the skill 3. Document exact behavior: choices, rationalizations (verbatim), failures **GREEN — Write minimal skill:** 1. Address the specific rationalizations observed in RED 2. Don't add content for hypothetical cases 3. Run same scenarios WITH skill — agent should now comply **REFACTOR — Close loopholes:** 1. Identify new rationalizations from testing 2. Add explicit counters for each 3. Build rationalization table, red flags list 4. Re-test until bulletproof **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. ## Claude Search Optimization (CSO) Future Claude needs to FIND your skill: 1. **Rich description** — "Use when..." with concrete triggers and symptoms 2. **Keyword coverage** — Error messages, symptoms, synonyms, tool names 3. **Descriptive naming** — Verb-first, active voice (`condition-based-waiting` not `async-test-helpers`) 4. **Token efficiency** — Frequently-loaded skills <200 words; move details to references ## Skill Types & Testing | 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 | ## Progressive Disclosure Patterns **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. ## Common Mistakes - Descriptions that summarize workflow (Claude takes shortcut, skips body) - Narrative storytelling instead of reusable patterns - Multi-language dilution (one excellent example beats many mediocre ones) - Code in flowcharts (can't copy-paste) - Deeply nested references (keep one level deep) - Skipping testing ("obviously clear" to you != clear to agents) ## Flowcharts Use ONLY for non-obvious decisions, process loops, or A-vs-B choices. Never for reference material, code examples, or linear instructions. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/koolamusic) — claim your Tome and manage your conversions.