Guide to effective Claude Code skill authoring using TDD methodology and persuasion principles. Use when creating new skills, improving compliance, or validating quality before deployment. Do not use for evaluating existing skills (use skills-eval) or analyzing architecture (use modular-skills). Follow the Iron Law: write a failing test before writing any skill.
Guides skill creation using test-driven development and persuasion principles to ensure measurable behavioral changes.
/plugin marketplace add athola/claude-night-market/plugin install abstract@claude-night-marketThis skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdmodules/anti-rationalization.mdmodules/deployment-checklist.mdmodules/description-writing.mdmodules/graphviz-conventions.mdmodules/persuasion-principles.mdmodules/progressive-disclosure.mdmodules/tdd-methodology.mdscripts/skill_validator.pyWriting effective Claude Code skills requires Test-Driven Development (TDD) and persuasion principles from compliance research. We treat skill writing as process documentation that needs empirical validation rather than just theoretical instruction. Skills are behavioral interventions designed to change model behavior in measurable ways.
By using TDD, we ensure skills address actual failure modes identified through testing. Optimized descriptions improve discovery, while a modular structure supports progressive disclosure to manage token usage. This framework also includes anti-rationalization patterns to prevent the assistant from bypassing requirements.
NO SKILL WITHOUT A FAILING TEST FIRST
Every skill must begin with documented evidence of Claude failing without it. This validates that you are solving a real problem. No implementation should proceed without a failing test, and no completion claim should be accepted without evidence. Detailed enforcement patterns for adversarial verification and coverage gates are available in imbue:proof-of-work.
We categorize skills into three types: Technique skills for specific methods, Pattern skills for recurring solutions, and Reference skills for quick lookups and checklists. This helps organize interventions into the most effective format for the task.
```bash
python scripts/analyze.py
python scripts/tokens.py ```
```bash
python scripts/abstract_validator.py --check ```
Verification: Run analysis and review token estimates before proceeding.
Skill descriptions must be optimized for semantic search and explicit triggering. Follow the formula [What it does] + [When to use it] + [Key triggers]. Use a third-person voice (e.g., "Guides...", "Provides...") and include specific, concrete use cases. Avoid marketing language or vague phrases like "helps with coding."
Skill description character budgets now scale with context window at 2% of available context. This means:
| Context Window | Description Budget |
|---|---|
| 200K (standard) | ~4,000 characters |
| 1M (Opus 4.6 beta) | ~20,000 characters |
Previously constrained skills can use more descriptive text on larger windows. However, keep descriptions concise regardless — longer is not better. The scaling primarily prevents truncation for skills with legitimately complex trigger conditions, not as an invitation to add verbose content.
Plugin names are now automatically shown alongside skill descriptions in the /skills menu. Do not repeat the plugin name in skill descriptions — it is redundant and wastes character budget. Focus descriptions on what the skill does and when to use it.
Establish empirical evidence that an intervention is needed. Create at least three pressure scenarios that combine time pressure and ambiguity. Run these in a fresh instance without the skill active and document the exact failures, such as skipped error handling or missing validation.
Create the smallest intervention that addresses the documented failures. Write the SKILL.md with required frontmatter and content that directly counters the baseline failures. Include one example of correct behavior and verify that the same pressure scenarios now show measurable improvement.
Eliminate the ability for Claude to explain away requirements. Run pressure scenarios with the skill active to identify common rationalizations, such as claiming a task is "too simple" for the full process. Add explicit counters, such as exception tables and red flag lists, until rationalizations stop.
Skills must explicitly counter patterns where Claude attempts to bypass requirements. Common excuses include claiming a task is "too simple" or that a "spirit vs letter of the law" approach is sufficient. Skills should include red flag lists for self-checking, such as "Stop if you think: this is too simple for the full process." When exceptions are necessary, document them explicitly to prevent unauthorized shortcuts.
For detailed implementation guidance:
modules/tdd-methodology.md for RED-GREEN-REFACTOR cycle detailsmodules/persuasion-principles.md for compliance research and techniquesmodules/description-writing.md for discovery optimizationmodules/progressive-disclosure.md for file structure patternsmodules/anti-rationalization.md for bulletproofing techniquesmodules/graphviz-conventions.md for process diagram standardsabstract:subagent-testing skill for pressure testing methodologymodules/deployment-checklist.md for final validationBefore deploying, verify that the RED, GREEN, and REFACTOR phases are complete and documented. Frontmatter must be valid, descriptions optimized, and line counts kept under 500 lines. Ensure all module references are valid and at least one concrete example is included.
All markdown files must pass scribe validation. This includes a slop scan to ensure a score under 2.5 and doc verification to confirm all file paths and command examples work. Bullet-to-prose ratios must remain under 60% to maintain readability. Use Skill(scribe:slop-detector) and Skill(scribe:doc-verify) for these checks.
Individual skills are created using skill-authoring, while modular-skills handles the architecture of larger structures. skills-eval provides ongoing quality assessment. Avoid the common pitfall of writing skills based on theoretical behavior; always use documented failures to guide development. Use progressive disclosure to prevent monolithic files and ensure that each intervention remains focused and token-efficient.
Skill not loading Check YAML frontmatter syntax and required fields
Token limits exceeded Use progressive disclosure - move details to modules
Modules not found Verify module paths in SKILL.md are correct
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.