Skill Authoring

Skill Authoring Guide

Overview

Writing 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.

The Iron Law

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.

Skill Types

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.

Quick Start

Skill Analysis

\\\`bash

Analyze skill complexity

python scripts/analyze.py

Estimate tokens

python scripts/tokens.py \\\`

Validation

\\\`bash

Validate skill structure

python scripts/abstract_validator.py --check \\\`

Verification: Run analysis and review token estimates before proceeding.

Description Optimization

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 Character Budget (Claude Code 2.1.32+)

Skill description character budgets now scale with context window at 2% of available context. This means:

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 Name Auto-Display (Claude Code 2.1.33+)

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.

The TDD Cycle for Skills

RED Phase: Document Baseline Failures

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.

GREEN Phase: Minimal Skill Implementation

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.

REFACTOR Phase: Anti-Rationalization

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.

Anti-Rationalization

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.

Module References

For detailed implementation guidance:

Core authoring cycle:

• TDD Methodology: See modules/tdd-methodology.md for RED-GREEN-REFACTOR cycle details
• Persuasion Principles: See modules/persuasion-principles.md for compliance research and techniques
• Description Writing: See modules/description-writing.md for discovery optimization
• Progressive Disclosure: See modules/progressive-disclosure.md for file structure patterns
• Anti-Rationalization: See modules/anti-rationalization.md for bulletproofing techniques
• Graphviz Conventions: See modules/graphviz-conventions.md for process diagram standards

Working with concrete skills (load when implementing or debugging):

• Annotated Examples: See modules/examples.md for walk-throughs of well-authored skills in this repo
• Advanced Patterns: See modules/advanced-patterns.md for skill-to-skill coordination, conditional behavior, and scaling across activation contexts
• Authentication: See modules/authentication.md for skills that invoke gh, glab, MCP servers, or other authenticated tools
• Error Handling: See modules/error-handling.md for missing tools, timeouts, partial subagent results, and permission denials
• Troubleshooting: See modules/troubleshooting.md for diagnosing skills that do not behave as the test corpus says they should

Validation and deployment (load when shipping):

• Validation: See modules/validation.md for frontmatter parsing, reference resolution, and structural checks before merge
• Testing with Subagents: See modules/testing-with-subagents.md for running the Iron Law test in a fresh subagent (and abstract:subagent-testing for the broader pressure-testing methodology)
• Deployment Checklist: See modules/deployment-checklist.md for final validation before promoting a skill

Deployment and Quality Gates

Before 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.

Scribe Validation

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 Agent(scribe:doc-verifier) for these checks.

Integration and Best Practices

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 Directory Variable (2.1.69+)

Skills can reference their own directory using ${CLAUDE_SKILL_DIR} in SKILL.md content. This variable resolves to the absolute path of the directory containing the SKILL.md file. Use it for referencing sibling files, data assets, or module paths without hardcoding absolute paths:

See `${CLAUDE_SKILL_DIR}/modules/advanced-patterns.md`
for detailed patterns.

Run: `python3 ${CLAUDE_SKILL_DIR}/scripts/check.py`

This is especially useful for skills that ship alongside scripts or data files and need portable path references that work regardless of where the plugin is installed.

Description Colon Fix (2.1.69+)

Skill descriptions containing colons (e.g., description: "Triggers include: X, Y, Z") previously failed to load from SKILL.md frontmatter. This is fixed in 2.1.69. Skills without a description: field also now appear in the available skills list (previously they were silently excluded).

Troubleshooting

Common Issues

Skill not loading Check YAML frontmatter syntax and required fields. As of 2.1.69, skills without a description: field still appear in the skills list, but descriptions with colons must be quoted in YAML frontmatter.

Token limits exceeded Use progressive disclosure - move details to modules

Modules not found Verify module paths in SKILL.md are correct

Advanced Skill-Authoring Patterns

Patterns for skill authors who have shipped a working skill and now need to coordinate with other skills, scale across many activation contexts, or expose conditional behavior. Read this after the core SKILL.md and tdd-methodology.md modules. The Iron Law still applies: every advanced pattern below assumes a baseline failing test exists for the behavior being added.

When to reach for these patterns

Most skills do not need any of this. Add an advanced pattern only when a baseline scenario fails because of coordination, scale, or context, not because of missing content. If the failure can be fixed by adding a section to a single SKILL.md, do that first.

Multi-skill coordination

Skills frequently overlap. abstract:skill-authoring writes new skills, abstract:skills-eval audits them, and abstract:subagent-testing validates them. When a task touches all three, the user does not want three skills shouting in parallel. They want a chain.

Establish a primary skill per task

In each SKILL.md, declare which other skills it defers to and which it owns. Example from abstract:skill-authoring/SKILL.md:

## Integration and Best Practices

Individual skills are created using `skill-authoring`, while
`modular-skills` handles the architecture of larger structures.
`skills-eval` provides ongoing quality assessment.

This single paragraph prevents the three skills from racing. The user reading any one of them learns where the boundaries live.

Cross-reference real targets, not abstractions

Use the fully qualified plugin:skill form so the reference resolves regardless of which marketplace the user installed:

For pressure testing the new skill, see
`Skill(abstract:subagent-testing)`.

Anti-pattern: see the testing skill. There are six skills with "testing" in the name across this repo. The reader cannot route.

Hand off, do not duplicate

When skill A needs behavior owned by skill B, link to skill B rather than restating its content. Duplicated guidance drifts. The version in abstract:skill-authoring will say one thing and the copy in abstract:skills-eval will say something else after two PRs. Pick an owner and link.

Hub-and-spoke loading

The hub-and-spoke pattern is documented in progressive-disclosure.md. The advanced variant adds two rules that only matter once a skill has 5+ modules.

Rule 1: the hub never loads more than two spokes

If your SKILL.md routinely says "for X, see module-a; for Y, see module-b; for Z, see module-c," the hub is doing too much. Either collapse the three modules into one, or split the hub into multiple skills. A reader who must load four files to start working has lost progressive disclosure.

Rule 2: spokes do not chain

A spoke that says "see other-spoke.md for prerequisites" forces sequential loading and defeats the model. If two spokes share foundational content, extract a third spoke and have the hub load it explicitly when needed. See Skill(abstract:modular-skills) for the full chain-elimination algorithm.

Dynamic activation via description triggers

Skills activate by semantic match on the description: field. Authors of mature skills tune triggers deliberately rather than listing every possible synonym.

Use specific noun phrases, not generic verbs

The generic form competes with every other skill in the category. The specific form fires only when the user actually needs this skill. Test specificity by running a real user prompt through /skills and checking activation rank.

Front-load the use case

The first 50 characters of description: carry the most weight in semantic matching. Lead with the action and the trigger:

description: 'Audit hooks for security and SDK compliance.
  Use when reviewing hook PRs or auditing plugin safety.'

Not:

description: 'A thorough framework that helps developers think
  carefully about hook quality across many dimensions...'

The second form buries the trigger past the truncation point on small context windows.

Conditional activation

Some skills should only fire in certain environments (CI vs local) or for certain file types. Two mechanisms exist.

Path globs for file-scoped skills

The paths: field activates a skill only when the conversation references matching files. Example for a skill that should only load when editing Python tests:

paths:
  - "**/test_*.py"
  - "**/tests/**/*.py"

This is enforced by the harness rather than by Claude. A skill with a paths: glob will not appear in /skills for unrelated edits.

Explicit gates inside the skill

For runtime gates the harness cannot check (e.g., "only run when a PR is open"), put a gate at the top of SKILL.md:

## Activation Gate

This skill requires:
- A current branch other than `master`
- An open PR for the current branch (verify with `gh pr view`)

If either condition fails, stop and tell the user this skill does
not apply. Do not silently proceed.

The gate is a behavioral instruction. Pair it with a baseline test that runs the skill on master and verifies Claude refuses.

Shared module extraction

When three or more skills reference the same content, extract it to plugins/<plugin>/skills/shared-patterns/modules/ and link from each consumer. The abstract:shared-patterns skill owns this directory in the abstract plugin.

Migration anti-pattern

The deprecated location was skills/shared/modules/ at the plugin root. The current evaluator (plugins/abstract/scripts/skills_auditor.py) flags any skills/shared/ path as a structural warning. Move the file into the consuming skill's modules/ directory or into shared-patterns/modules/ with cross-references.

Anti-patterns

These are common ways advanced patterns fail in review.

"Skill of skills"

A SKILL.md that consists entirely of links to other skills provides no value. The user could have run /skills themselves. A hub skill must contain at least one substantive section that adds context the linked skills cannot provide on their own.

Trigger sprawl

Adding every keyword you can think of to description: to "improve discovery" actually degrades it. Each irrelevant keyword dilutes the signal of the relevant ones. Cap descriptions at three trigger phrases and test activation against real prompts.

Conditional gates without tests

A gate that says "only use in production environments" is a behavioral promise. Without a baseline test that runs the skill in development and verifies refusal, the gate is decoration. Claude will rationalize past it under pressure. See anti-rationalization.md for the counter pattern.

Spoke depth creep

A spoke module that grew from 200 to 800 lines and now contains its own subsections probably needs to become two spokes. Split when a module has more than three top-level sections.

Verification

Before merging an advanced pattern:

# Confirm the hub stays under 500 lines
wc -l plugins/<plugin>/skills/<skill>/SKILL.md

# Confirm activation against a real prompt (manual)
# Run the user prompt in a fresh session and check /skills
# output for rank and load order.

# Confirm the auditor sees no shared/ regressions
python plugins/abstract/scripts/skills_auditor.py \
  --skill plugins/<plugin>/skills/<skill>/SKILL.md

Cross-reference: see Skill(abstract:modular-skills) for the full hub-and-spoke specification and chain-elimination rules.

Anti-Rationalization Techniques

Overview

Claude is sophisticated at finding justifications to bypass requirements while appearing compliant. Skills must explicitly counter these rationalization patterns to maintain effectiveness.

Understanding Rationalization

What It Is

Rationalization: The process of finding logical-sounding reasons to justify not following a requirement, even when the requirement clearly applies.

Why It Happens

1. Path of Least Resistance: Following requirements takes effort; bypassing is easier 2. Context Sensitivity: Claude tries to optimize for perceived user intent 3. Ambiguity Exploitation: Any wiggle room gets exploited 4. Confidence Bias: "I know what the user really wants"

Example

Requirement: "Every API endpoint must include input validation"

User Request: "Quickly add a user profile update endpoint"

Rationalization:

"Since this is a quick implementation for an internal tool,
we can use basic validation now and add detailed
validation in a later iteration. The user emphasized speed,
so I'll focus on core functionality first."

Why It's Wrong: Requirement has no "unless it's quick" exception. Security doesn't wait for "later iterations."

Common Rationalization Patterns

Pattern 1: Scope Minimization

Rationalization: "This is just X, so Y doesn't apply"

Variations:

• "This is just a prototype"
• "This is just an internal tool"
• "This is just a simple endpoint"
• "This is just for testing"

Counter Strategy: Universal Application Table

## When This Requirement Applies

| Scope | Required? | Rationale |
|-------|-----------|-----------|
| Production | OK | Security non-negotiable |
| Prototype | OK | Prototypes → production |
| Internal | OK | Internal = attack vector |
| Simple | OK | Complexity ≠ security need |
| Testing | OK | Test environments get exposed |
| Quick fix | OK | Breaches are permanent |

**No exceptions**. Only valid override: Explicit user statement
"Skip [requirement] because [documented reason]."

Pattern 2: Temporal Deferral

Rationalization: "We can add X later"

Variations:

• "We'll add security in the next iteration"
• "Let's get it working first, then harden"
• "We can refactor later when we have time"
• "I'll add tests after we ship"

Counter Strategy: Immediacy Requirement

## No Deferral Allowed

These requirements apply NOW, not later:
- Input validation
- Error handling
- Authentication
- Tests

### Why "Later" Fails

Statistics from 1,000+ projects:
- 80% of "later" items never happen
- Security added later requires 3x effort
- Bugs found post-deployment cost 15x more

### The Rule

If it's important enough to do "later," it's important
enough to do now. If it's not important enough to do now,
remove it from the plan entirely.

Pattern 3: Trust Assumptions

Rationalization: "We can skip X because users are trusted"

Variations:

• "These are our developers, they won't abuse it"
• "Only admins access this"
• "We control the clients"
• "It's behind our firewall"

Counter Strategy: Trust Boundaries Table

## Trust Is Not A Security Control

| "Trusted" Context | Why It's Still Vulnerable |
|-------------------|---------------------------|
| Internal users | Compromised accounts have high privilege |
| Developers | Make mistakes, get phished, leave company |
| Admin only | Admins are prime targets |
| Controlled clients | Clients get modified/reverse-engineered |
| Behind firewall | Firewalls get breached, insiders exist |

### Security Controls Apply Everywhere

Authentication, validation, and error handling are not
optional in "trusted" contexts. They're more important
because trusted contexts have elevated access.

Pattern 4: Complexity Trade-offs

Rationalization: "X would make the code too complex"

Variations:

• "Adding validation clutters the code"
• "Error handling makes it harder to read"
• "Tests would double the code size"
• "This would over-engineer a simple feature"

Counter Strategy: Complexity Reality Check

## Real Complexity Costs

### Adding Security: +15% code, -95% vulnerabilities

Without validation: 5 lines

@app.post("/user") def update_user(data: dict): return db.update(data)

With validation: 6 lines (+20%)

@app.post("/user") def update_user(data: UserUpdate): # Pydantic model return db.update(data)

### Skipping Security: -15% code, +1000% incident cost
- Code: 15% less to write
- Breach: $4.35M average cost
- Reputation: Permanent damage

### The Math
Writing secure code costs 15% more upfront.
Fixing breaches costs 1000% more later.

Pattern 5: Spirit vs Letter

Rationalization: "I understand the spirit, so I can adapt the letter"

Variations:

• "The principle here is X, so Y isn't needed"
• "The real intent is X, not this specific requirement"
• "I'm following the spirit even if not exact steps"
• "A better approach achieves the same goal"

Counter Strategy: Explicit Primacy

## Foundational Requirements Come First

OK **Follow these EXACTLY:**
1. [Specific requirement 1]
2. [Specific requirement 2]

OK **Then apply judgment:**
- Adapt implementation details
- Choose appropriate tools
- Optimize for context

 **Don't reinterpret:**
- Core requirements
- Security controls
- Quality gates

### The Hierarchy

1. **Foundational requirements**: Follow exactly
2. **Implementation details**: Use judgment
3. **Optimizations**: Context-dependent

If you're unsure which category a requirement is in,
treat it as foundational.

Pattern 6: Confidence Bias

Rationalization: "I know this domain well, so I can skip the checklist"

Variations:

• "I've done this 100 times, I don't need the skill"
• "This is basic stuff, no need for the full process"
• "I remember the key points"
• "The skill is for beginners"

Counter Strategy: Universal Process

## Expertise Doesn't Exempt You

### Why Experts Need Skills Most

| Level | Risk Without Process |
|-------|---------------------|
| Beginner | Doesn't know what to do → Seeks guidance |
| Intermediate | Knows basics → Follows process carefully |
| **Expert** | **Overconfident → Skips "obvious" steps** |

### Expert Failure Modes
- Complacency: "I know this"
- Autopilot: Muscle memory skips steps
- Assumption: Context fills gaps mentally
- Speed: Pressure to go fast → shortcuts

### The Surgeon Principle

Surgeons use checklists every time.
Pilots use checklists every time.
Experts in high-stakes fields NEVER skip basics.

Your code is high-stakes. Use the checklist.

Red Flags List Pattern

Purpose: Create self-checking mechanism for Claude

Structure:

## Red Flags That You're Rationalizing

Stop immediately if you think:

**Scope Minimization:**
- "This is just a [prototype/internal/simple] X"
- "This is only for [testing/development]"

**Temporal Deferral:**
- "We can add [security/tests/validation] later"
- "Let's get it working first, then [requirement]"

**Trust Assumptions:**
- "These are trusted [users/developers/admins]"
- "It's behind [firewall/auth/access control]"

**Complexity Trade-offs:**
- "Adding [requirement] would over-engineer this"
- "[Requirement] makes the code too complex"

**Spirit vs Letter:**
- "I understand the principle, so I can skip this specific step"
- "A better approach achieves the same goal"

**Confidence Bias:**
- "I've done this many times, no need for the full process"
- "This is basic stuff"

### What To Do Instead

1. Acknowledge the thought
2. Check the exception table
3. If no explicit exception, follow requirement
4. If genuinely unsure, ask user

Exception Tables

Purpose: Explicitly define when requirements don't apply (usually: never)

Structure

## Requirement Exceptions

| Requirement | Applies To | Exceptions |
|-------------|------------|------------|
| Input validation | All endpoints | None |
| Authentication | All state changes | Public read-only endpoints |
| Error handling | All operations | None |
| Tests | All features | Spike/prototype with < 24hr lifetime |
| Logging | All failures | None |

### How To Use

1. Check if your scenario matches an exception
2. If no match, requirement applies
3. If unsure, requirement applies
4. If user explicitly overrides, document why

The "No Exceptions" Row

For truly universal requirements:

| Input validation | Every endpoint | **No exceptions** |

Makes rationalization explicit: "The table says no exceptions, but I think..."

Commitment Statements

Purpose: Create cognitive dissonance when bypassing requirements

Pre-Work Commitment

## Before Starting

Declare out loud:

"I am using [skill name] for this task.
I commit to:
- Reading ALL requirements before starting
- Following requirements exactly as written
- Not taking shortcuts based on perceived simplicity
- Not deferring required elements to 'later'
- Asking for clarification rather than assuming exceptions

If I think an exception applies, I will:
1. Check the exception table
2. Ask the user if not explicitly covered
3. Document the decision

During-Work Checkpoints

## At Each Decision Point

Ask yourself:
- "Am I following the skill requirements?"
- "Or am I finding reasons to bypass them?"
- "Would I explain this decision as 'just this once' or 'special case'?"

If any rationalization detected, stop and recalibrate.

Post-Work Verification

## After Completion

Verify explicitly:
- [ ] All requirements applied
- [ ] No deferred items ("we'll add later")
- [ ] No exceptions taken without user approval
- [ ] No rationalizations accepted

Sign off: "I followed ALL requirements without exception."

Escape Hatch Prevention

Purpose: Block common ways Claude tries to get around requirements

Pattern: The Suggestion Hedge

Attempted Bypass:

"Here's the implementation. You might want to consider
adding input validation later for production use."

Counter:

## No Suggestions For Required Items

Don't say:
- "Consider adding [requirement]"
- "You might want to [requirement]"
- "It would be good to [requirement]"

If it's required, include it. Period.

Pattern: The Future Tense

Attempted Bypass:

"This endpoint will need authentication before deployment."

Counter:

## Present Tense Requirements

Write: "This endpoint requires authentication."
Not: "This will need..." or "This should have..."

If it's required, implement it now, not later.

Pattern: The Conditional

Attempted Bypass:

"If this is going to production, add rate limiting."

Counter:

## No Conditionals For Required Items

Assume production-quality unless explicitly told otherwise.

Don't say: "If production, then [requirement]"
Do say: "[Requirement] is included"

Default: Ship-quality code every time.

Strength Calibration

Different requirements need different enforcement levels:

Critical (Strongest)

Use for: Security, correctness, data integrity

Language:

• "MUST include"
• "Required in every case"
• "No exceptions"
• "Foundational requirement"

Tables:

• "No exceptions" in exception column
• Red flags lists
• Commitment statements

Important (Strong)

Use for: Best practices, testing, quality

Language:

• "Always include"
• "Required unless [specific exception]"
• "Default requirement"

Tables:

• Specific exceptions listed
• Clear override process

Recommended (Moderate)

Use for: Optimizations, preferences

Language:

• "Include when [conditions]"
• "Recommended for [scenarios]"
• "Consider for [use cases]"

Tables:

• Conditional application
• Trade-off guidance

Testing Rationalization Resistance

Methodology

1. Design Pressure Scenarios that invite rationalization 2. Run with skill active 3. Document rationalizations Claude attempts 4. Add explicit counters to skill 5. Retest until rationalizations stop

Example Test

Scenario:

"This is just a quick internal API for our dev team.
Add an endpoint to update user profiles. We're on a tight
deadline, so keep it simple."

Triggers:

• "just" (minimization)
• "internal" (trust assumption)
• "quick" (temporal pressure)
• "tight deadline" (justification)
• "keep it simple" (complexity trade-off)

Expected Rationalizations:

• Skip detailed validation (it's internal)
• Defer security (we're in a hurry)
• Skip tests (it's simple)

Success Criteria:

• Full validation included
• Security controls present
• Tests written
• No "we can add later" language

Common Mistakes

Vague Requirements

Problem:

"Add appropriate security controls."

Too much interpretation room.

Solution:

"Every endpoint must include:
1. Input validation with type and format checks
2. Authentication verification
3. Authorization for resource access
4. Rate limiting (10 req/min)

Missing Red Flags

Problem: No self-checking mechanism

Solution: Include explicit red flags list

Assuming Compliance

Problem: Not testing against rationalization scenarios

Solution: Run pressure tests, document bypasses, add counters

Summary

Anti-rationalization techniques:

1. Exception Tables: Define exactly when requirements don't apply (usually: never) 2. Red Flags Lists: Enable self-checking for rationalization patterns 3. Commitment Statements: Create cognitive dissonance for bypassing 4. Universal Application: Block "just this once" thinking 5. Immediacy Requirements: Prevent temporal deferral 6. Escape Hatch Prevention: Close common bypass patterns

Goal: Make it harder to rationalize than to comply.

Test: Run pressure scenarios specifically designed to trigger rationalizations. Add counters until they stop appearing.

Authentication in Skills

Skills frequently invoke authenticated tools: GitHub via gh, GitLab via glab, MCP servers that hold OAuth tokens, internal APIs that expect bearer tokens. This module covers how to author a skill that handles credentials safely. The Iron Law applies: write a baseline test where Claude leaks or mishandles a credential, then write the skill that prevents it.

Scope

This module is about authoring. For runtime patterns shared across skills (token rotation, OAuth dance, key storage), defer to Skill(leyline:authentication-patterns). This module covers the authoring decisions: how the SKILL.md should describe auth, what to delegate, what to refuse.

Three auth shapes a skill must distinguish

Conflating these shapes produces skills that either ask the user for credentials they already have, or worse, write credentials into transcripts.

Pre-authenticated CLI tools

The common case. The user has already run gh auth login before starting Claude. Your skill should:

1. Verify the session at the top of the workflow. 2. Fail loudly with a remediation step if absent. 3. Never attempt to authenticate inline.

Pattern:

## Activation Gate

Before using this skill, verify `gh` is authenticated:

\`\`\`bash
gh auth status
\`\`\`

If the command returns a non-zero exit, stop and tell the user:
"This skill requires `gh` authentication. Run `gh auth login`
and retry." Do not attempt to log in on the user's behalf.

Why "do not attempt": running gh auth login opens a browser or prints a device code. Claude cannot complete either flow and will hang or hallucinate a success.

MCP server delegation

When the skill uses an MCP server (Gmail, Calendar, Drive, GitHub via MCP, Slack), the credential lives inside the MCP server, not the skill. The authoring rule is short: never read, log, or echo tokens from MCP context.

Pattern:

## Tools

This skill uses the `mcp__plugin_context7_context7__query-docs`
tool. The MCP server holds the credential. Do not request it
from the user. Do not print the configured server URL.

If the MCP tool returns an authentication error, surface the
error verbatim and tell the user to reauthenticate via their
MCP configuration.

The phrase "surface the error verbatim" matters. Skills that paraphrase auth errors lose the diagnostic detail (expired vs revoked vs scope mismatch) the user needs to fix the problem.

Bearer tokens and API keys

When a skill calls a custom API that needs a key, the key lives in an environment variable or a file the user controls. The skill must:

1. Document the variable name in SKILL.md. 2. Read it via the tool that needs it, not via Claude. 3. Refuse to proceed if absent. 4. Never print the value, even masked.

Pattern:

## Required Environment

This skill reads `EXAMPLE_API_KEY` from the environment when
running its scripts. Set it via your shell profile or a `.env`
file loaded by your harness:

\`\`\`bash
export EXAMPLE_API_KEY="..."
\`\`\`

The skill scripts read the variable directly. Do not paste the
key into the conversation. If `EXAMPLE_API_KEY` is unset, the
script exits with code 2 and prints a remediation message.

The "do not paste" line is enforcement, not politeness. Pasted keys end up in session transcripts, screenshots, and bug reports.

Delegating to authenticated subagents

When a parent skill dispatches a subagent that needs auth, the subagent inherits the parent's environment but not the parent's conversation. Two failure modes:

1. The subagent does not know what tools it has access to. 2. The subagent re-prompts for credentials the parent already verified.

Counter the first failure by passing the verified tool list explicitly in the dispatch prompt. Counter the second by including a sentence like "Auth has been verified by the parent. Do not re-verify or re-prompt the user."

Example dispatch fragment:

You are a subagent dispatched by `abstract:plugin-review`. The
parent has already verified `gh auth status` returned success.
Use `gh` directly. Do not run `gh auth login` or prompt for
credentials.

Authoring failure modes

These show up in baseline tests. Build the skill to prevent each.

Leak by example

A skill that demonstrates auth via curl -H "Authorization: Bearer sk-real-looking-key-12345" invites Claude to fill the header with whatever string looks plausible. Use placeholder syntax that cannot be mistaken for a real token:

curl -H "Authorization: Bearer ${API_KEY}" ...

The ${VAR} form makes it obvious the value comes from elsewhere.

Auth in the conversation

A skill that tells Claude "ask the user for their token" trains Claude to collect secrets in the chat window. Always direct secrets through the environment or the harness, never the conversation.

Silent fallback

A skill that says "if gh fails, try the GitHub REST API directly with a token" creates two auth paths. Pick one. If the primary fails, stop and report. Multiple paths multiply the ways the skill can leak.

Stale session assumptions

A skill that runs for 30 minutes may outlive the auth session that started it. For long-running skills, re-verify auth at phase boundaries, not just at the start.

Anti-patterns

Verification

Test that the skill behaves correctly when auth is missing. Sample baseline scenario:

Run the skill in a shell where `gh auth status` returns exit
code 1. Expected behavior: skill stops at the activation gate
and prints the remediation step. Failure: skill tries to log
in, prompts for a token, or proceeds without auth.

If the skill passes this scenario, the auth handling is at least defensive. Add a second scenario where the token is present but expired (simulate by setting GH_TOKEN=invalid) and verify the skill surfaces the error rather than retrying.

Cross-reference: see Skill(leyline:authentication-patterns) for runtime patterns (token rotation, OAuth, secret storage) that this module deliberately does not duplicate.

Deployment Checklist

Overview

Final validation checklist before deploying a skill. validates quality, completeness, and effectiveness through systematic verification.

Pre-Deployment Gates

Skills must pass ALL gates before deployment. No exceptions.

Gate 1: Empirical Testing Complete

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

RED Phase Verification

• [ ] 3+ baseline scenarios documented
• [ ] Tests run in fresh Claude instances (no context contamination)
• [ ] Full responses captured verbatim (no editing)
• [ ] Failures categorized and analyzed
• [ ] Patterns identified across scenarios
• [ ] Compliance baseline measured (percentage)

Evidence Required: Baseline test documentation in tests/baseline/

GREEN Phase Verification

• [ ] Same scenarios tested with skill active
• [ ] Tests run in fresh instances (different from baseline)
• [ ] Measurable improvement demonstrated (≥50%)
• [ ] Compliance increase quantified
• [ ] Remaining issues documented
• [ ] Partial improvements explained

Evidence Required: With-skill test documentation in tests/with-skill/

REFACTOR Phase Verification

• [ ] Rationalization scenarios designed
• [ ] Adversarial testing completed
• [ ] Rationalizations documented verbatim
• [ ] Explicit counters added to skill
• [ ] Regression testing passed
• [ ] 3+ consecutive tests with 100% compliance

Evidence Required: Rationalization test documentation in tests/rationalization/

Gate 2: Structure and Format

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

SKILL.md Requirements

• [ ] File named exactly SKILL.md (case-sensitive)
• [ ] YAML frontmatter present and valid
• [ ] Required frontmatter fields complete:
• [ ] name (lowercase, hyphens, ≤64 chars)
• [ ] description (third person, ≤1024 chars)
• [ ] version (semver format)
• [ ] category (valid category)
• [ ] tags (relevant keywords)
• [ ] estimated_tokens (realistic)
• [ ] Line count under 500 lines
• [ ] Markdown syntax valid
• [ ] No broken links or references

Module Requirements (if applicable)

• [ ] Module files in modules/ directory
• [ ] Module files 200-400 lines each
• [ ] One level reference depth only
• [ ] All references from SKILL.md exist
• [ ] No circular references
• [ ] Module topics focused and distinct

Sandbox Compatibility (Claude Code 2.1.38+)

• [ ] Skill does not require runtime writes to .claude/skills/ (blocked in sandbox mode)
• [ ] If skill creates/modifies other skills, documented as requiring non-sandbox mode

Script Requirements (if applicable)

• [ ] Scripts in scripts/ directory
• [ ] Execute permissions set correctly
• [ ] Script documentation present
• [ ] Dependencies documented
• [ ] Error handling implemented
• [ ] Test coverage exists

Gate 3: Description Optimization

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

Voice and Clarity

• [ ] Third person voice ("Guides...", "Teaches...", "Provides...")
• [ ] NOT first person ("I help...", "We teach...")
• [ ] Active, specific verbs used
• [ ] No marketing language or hyperbole
• [ ] Clear, concrete language (not vague)

Discovery Optimization

• [ ] Includes "Use when..." clause
• [ ] 3+ specific use cases listed
• [ ] Key discovery terms included
• [ ] Domain-specific terminology present
• [ ] Length 200-400 characters (optimal)
• [ ] Distinguishes from similar skills

Validation Test

• [ ] Passes skill_validator.py description checks
• [ ] Discovery tested with sample queries
• [ ] Activation reliable for target scenarios

Gate 4: Content Quality

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

Core Content

• [ ] Overview section clear and complete
• [ ] "When to Use" section explicit
• [ ] Quick Start provides minimal example
• [ ] Common tasks identified
• [ ] Module references clear and actionable
• [ ] No orphaned sections

Examples

• [ ] At least one complete example in SKILL.md
• [ ] Example shows typical usage
• [ ] Example demonstrates key features
• [ ] Additional examples in modules (if needed)
• [ ] Examples are realistic (not theoretical)

Anti-Rationalization

• [ ] Red flags list included
• [ ] Exception table present (if applicable)
• [ ] Commitment statements added (if applicable)
• [ ] Common rationalizations explicitly countered
• [ ] No ambiguous requirements

Gate 5: Technical Validation

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

Automated Validation

# Run skill validator
python scripts/skill_validator.py

# Expected: Exit code 0 (success)
# Acceptable: Exit code 1 (warnings only)
# Must fix: Exit code 2 (errors)

Validation results:

• [ ] Exit code 0 or 1
• [ ] No critical errors
• [ ] All warnings reviewed
• [ ] Validation report saved

Manual Checks

• [ ] YAML parses correctly
• [ ] All file references valid
• [ ] No dead links in documentation
• [ ] Token estimate verified
• [ ] Dependencies exist and load
• [ ] No syntax errors in examples

Gate 6: Integration Testing

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

Isolation Testing

• [ ] Skill loads without errors
• [ ] No conflicts with other skills
• [ ] Dependencies resolve correctly
• [ ] Module loading works
• [ ] Scripts execute successfully

Workflow Testing

• [ ] Typical workflow tested end-to-end
• [ ] Edge cases verified
• [ ] Error conditions handled
• [ ] Integration with dependent skills tested
• [ ] No unexpected side effects

Cross-Platform Testing (if applicable)

• [ ] Tested on primary platform
• [ ] Path separators correct
• [ ] File permissions appropriate
• [ ] Scripts portable

Gate 7: Documentation

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

User-Facing Documentation

• [ ] README.md exists (if plugin-level)
• [ ] Installation instructions clear
• [ ] Usage examples complete
• [ ] Troubleshooting section included
• [ ] Common issues documented

Developer Documentation

• [ ] Test results documented
• [ ] Improvement history tracked
• [ ] Known limitations listed
• [ ] Future enhancements noted
• [ ] Maintenance notes added

Gate 8: Compliance and Standards

Status: [ ] Not Started | [ ] In Progress | [ ] Complete

Skill Standards

• [ ] Follows modular-skills architecture patterns
• [ ] Adheres to progressive disclosure principles
• [ ] Uses persuasion principles appropriately
• [ ] Implements anti-rationalization techniques
• [ ] Token efficiency optimized

Code Quality (for scripts)

• [ ] Type hints present (Python)
• [ ] Error handling detailed
• [ ] Logging implemented
• [ ] Security reviewed
• [ ] No hardcoded secrets

Ethical Review

• [ ] Persuasion serves user interests
• [ ] No manipulative language
• [ ] Transparency about intent
• [ ] Appropriate strength calibration
• [ ] User override possible

Quick Validation Command

# Run all automated checks
make validate-skill PATH=/path/to/skill/SKILL.md

# Or manually:
python scripts/skill_validator.py --path /path/to/skill/SKILL.md --strict

Validation Script Output

Expected output from skill_validator.py:

Skill Validation Report
=======================

Skill: skill-name (v1.0.0)
Path: /path/to/skill/SKILL.md

Structure Checks
----------------
OK SKILL.md exists
OK YAML frontmatter valid
OK Required fields present
OK Name format valid
OK Description format valid
OK Line count: 456/500
OK Module references valid

Content Checks
--------------
OK Third person voice
OK "Use when" clause present
OK Discovery terms included
OK Examples present
OK No broken links

Quality Checks
--------------
OK Token estimate reasonable
OK No empty sections
OK Version valid (semver)
! Warning: Description could include more discovery terms

Result: PASS (1 warning)
Exit Code: 1

Recommendation: Fix warnings before deployment (optional)

Deployment Steps

After passing all gates:

1. Final Review

# Review checklist completion
cat deployment-checklist.md

# Verify all gates marked complete
grep "\[x\]" deployment-checklist.md

2. Version Tag

# Tag release
git tag -a skill-name-v1.0.0 -m "Release skill-name v1.0.0"

# Push tag
git push origin skill-name-v1.0.0

3. Documentation Update

# Update changelog
echo "## v1.0.0 - $(date +%Y-%m-%d)" >> CHANGELOG.md
echo "- Initial release" >> CHANGELOG.md

# Update registry (if applicable)
# Add to skill registry/catalog

4. Deployment

# Copy to deployment location
cp -r skill-name ~/.claude/skills/

# Or install via package manager
claude-skills install skill-name

# Verify installation
claude-skills list | grep skill-name

5. Post-Deployment Verification

# Test in production environment
# Run smoke tests
# Verify skill activates correctly
# Confirm expected behavior

Rollback Plan

If issues discovered post-deployment:

Immediate Actions

1. Document Issue

• Exact failure observed
• Reproduction steps
• Impact assessment

2. Rollback Decision

• Minor issue: Hot fix acceptable?
• Major issue: Immediate rollback required?

3. Execute Rollback (if needed)

   # Revert to previous version
   git revert skill-name-v1.0.0

   # Or restore previous version
   cp -r skill-name.backup ~/.claude/skills/skill-name

Fix and Redeploy

1. Fix issue in development 2. Re-run affected gate checks 3. Update version number 4. Re-deploy with new version

Success Criteria Summary

Minimum requirements for deployment:

1. Empirical Testing: 3+ baseline scenarios, ≥50% improvement, 3+ consecutive 100% compliance tests 2. Structure: Valid YAML, <500 lines, proper file organization 3. Description: Third person, "Use when" clause, 200-400 chars, discovery optimized 4. Content: Clear overview, examples, anti-rationalization, no orphans 5. Validation: Passes skill_validator.py with exit code 0 or 1 6. Integration: Loads without errors, no conflicts, workflows tested 7. Documentation: Complete user and developer docs 8. Standards: Follows best practices, ethical review passed

Any gate failure = DO NOT DEPLOY

Post-Deployment Monitoring

Week 1: Active Monitoring

• [ ] Monitor activation rates
• [ ] Collect user feedback
• [ ] Watch for unexpected behaviors
• [ ] Review error logs
• [ ] Track compliance rates

Week 2-4: Adjustment Period

• [ ] Analyze usage patterns
• [ ] Identify improvement opportunities
• [ ] Plan updates if needed
• [ ] Document lessons learned

Month 2+: Maintenance

• [ ] Periodic regression testing
• [ ] Update for new best practices
• [ ] Incorporate user feedback
• [ ] Maintain compatibility

Continuous Improvement

After deployment, track:

1. Activation Success Rate: How often skill activates when it should 2. Compliance Rate: How often Claude follows all requirements 3. User Satisfaction: Feedback and issue reports 4. Performance: Token usage, latency, context efficiency 5. Maintenance Cost: Time spent on updates and fixes

Use metrics to guide future improvements.

Checklist Template

# Deployment Checklist: [Skill Name] v[Version]

Date: YYYY-MM-DD
Developer: [Name]

## Gate 1: Empirical Testing
- [ ] RED phase complete
- [ ] GREEN phase complete
- [ ] REFACTOR phase complete

## Gate 2: Structure and Format
- [ ] SKILL.md requirements met
- [ ] Module requirements met (if applicable)
- [ ] Script requirements met (if applicable)

## Gate 3: Description Optimization
- [ ] Voice and clarity verified
- [ ] Discovery optimization complete
- [ ] Validation tests passed

## Gate 4: Content Quality
- [ ] Core content complete
- [ ] Examples included
- [ ] Anti-rationalization implemented

## Gate 5: Technical Validation
- [ ] Automated validation passed
- [ ] Manual checks complete

## Gate 6: Integration Testing
- [ ] Isolation testing passed
- [ ] Workflow testing complete
- [ ] Cross-platform verified (if applicable)

## Gate 7: Documentation
- [ ] User-facing docs complete
- [ ] Developer docs complete

## Gate 8: Compliance and Standards
- [ ] Skill standards met
- [ ] Code quality verified (if applicable)
- [ ] Ethical review passed

## Validation Results
Validator exit code: [0/1/2]
Issues found: [Count]
Critical issues: [Count]

## Deployment Decision
[ ] APPROVED - All gates passed
[ ] APPROVED WITH WARNINGS - Minor issues documented
[ ] REJECTED - Must fix critical issues

Signature: ________________
Date: ________________

Summary

Deployment requires:

• 8 quality gates all passed
• Empirical testing complete with documented results
• Technical validation successful (validator exit code 0 or 1)
• No critical issues remaining

Golden rule: If you're unsure about any gate, that gate has NOT passed. Fix issues before deploying.

Description Writing for Skill Discovery

Overview

Skill descriptions are critical for Claude's skill selection process. They determine whether skills are discovered, activated, and used correctly. This module covers optimization techniques for writing descriptions that maximize discoverability.

Why Descriptions Matter

Discovery Process

When Claude encounters a task: 1. Semantic Search: Matches task description against skill descriptions 2. Relevance Ranking: Scores skills by description similarity 3. Context Check: Verifies "Use when" conditions match 4. Activation: Loads highest-scoring relevant skills

Implication: If your description doesn't match user language patterns, the skill won't be discovered.

Common Failures

Too Vague: "Helps with coding"

• Matches everything, provides no signal
• Can't distinguish from other skills

Too Specific: "Implements OAuth2 PKCE flow with rotating refresh tokens"

• Only matches exact terminology
• Misses general queries like "add authentication"

Missing Context: "Provides testing guidelines"

• Unclear when to use vs. other testing skills
• No activation triggers

Description Formula

[WHAT it does] + [WHEN to use it] + [KEY TRIGGERS/TERMS]

Components

1. WHAT: Clear action or capability (third person) 2. WHEN: Explicit "Use when..." clause 3. TRIGGERS: Domain-specific terms for discovery

Example

description: Guides secure API endpoint design with input validation, error handling, and authentication. Use when creating new endpoints, reviewing API security, or implementing REST services. Covers rate limiting, CORS, and security headers.

Breakdown:

• WHAT: "Guides secure API endpoint design with [specifics]"
• WHEN: "Use when creating new endpoints, reviewing API security, or implementing REST services"
• TRIGGERS: API, endpoint, validation, authentication, REST, rate limiting, CORS, security

Voice and Tone

Third Person Always

Correct:

• "Teaches..."
• "Provides..."
• "Guides..."
• "Implements..."
• "Analyzes..."

Incorrect:

• "I teach..."
• "We provide..."
• "Helps you..."
• "Will guide..."

Active, Specific Verbs

Strong Verbs:

• Guides, teaches, implements, validates, enforces
• Analyzes, optimizes, automates, generates
• validates, prevents, detects, corrects

Weak Verbs:

• Helps with, deals with, handles
• Supports, provides support for
• Assists in, aids in

Example Transformation

Weak:

description: Helps you write better tests for your code.

Strong:

description: Guides test-driven development using RED-GREEN-REFACTOR methodology. Use when writing new tests, refactoring code, or establishing testing discipline. Covers unit tests, integration tests, and test coverage strategies.

The "Use When" Clause

Purpose

Explicitly states activation conditions, helping both: 1. Claude: Understand when to activate skill 2. Users: Understand what skill is for

Structure

Use when [primary use case], [secondary use case], or [tertiary use case].

Examples

Specific Conditions:

Use when creating new API endpoints, reviewing security implementations, or debugging authentication issues.

Task Types:

Use when refactoring large files, optimizing code structure, or improving maintainability.

Problem Scenarios:

Use when tests are missing, coverage is low, or regression bugs appear frequently.

Too Vague:

Use when working with APIs.

Too Narrow:

Use when implementing OAuth2 PKCE flow specifically for mobile applications.

Key Terms for Discovery

Analysis of 100+ Skills

Common high-value discovery terms across successful skills:

Development Workflow:

• testing, TDD, refactoring, code review
• debugging, optimization, performance
• architecture, design patterns, structure

Language/Framework:

• Python, JavaScript, Rust, Go
• React, Django, Flask, Express
• async, typing, generics

Security:

• authentication, authorization, validation
• security, encryption, sanitization
• rate limiting, CORS, headers

Data:

• API, REST, GraphQL, database
• SQL, NoSQL, migrations
• serialization, validation

Quality:

• tests, coverage, quality, metrics
• documentation, standards, best practices
• compliance, validation, checking

Incorporating Discovery Terms

Technique: Include specific terms users might search for

# Too generic
description: Helps with Python code quality.

# Optimized for discovery
description: Analyzes Python code quality using type hints, async patterns, and testing best practices. Use when reviewing code, improving type safety, or optimizing async/await usage. Covers mypy, pytest, and performance profiling.

Discovery terms added:

• Python (language)
• type hints, typing (specific feature)
• async, await (pattern)
• mypy, pytest (tools)
• performance, profiling (category)

Length Considerations

Character Limits

Recommended: 200-400 characters Maximum: 1024 characters (hard limit) Minimum: 100 characters (for adequate context)

Optimization Strategy

Under 200 chars: Too brief, missing context → Add specific use cases or key features

200-400 chars: Ideal range → Balance specificity with readability

Over 600 chars: Too verbose → Move details to SKILL.md body, keep description focused

Example Progression

Too Short (85 chars):

description: Guides API security. Use when building APIs.

Optimal (285 chars):

description: Guides secure API endpoint design with input validation, error handling, and authentication best practices. Use when creating new endpoints, reviewing API security, or implementing REST/GraphQL services. Covers rate limiting, CORS, security headers, and common vulnerabilities.

Too Long (520 chars):

description: detailed guide to secure API endpoint design covering all aspects of security including input validation with regex and type checking, detailed error handling with proper HTTP status codes and error messages, authentication mechanisms including JWT and OAuth2, authorization with RBAC and ABAC, rate limiting strategies, CORS configuration, security headers like CSP and HSTS, and protection against common vulnerabilities including SQL injection, XSS, CSRF, and more.

Pattern Library

Technique Skills

Pattern:

Teaches [specific methodology] for [domain]. Use when [scenarios]. Covers [key aspects].

Example:

description: Teaches test-driven development using RED-GREEN-REFACTOR cycle for Python. Use when writing new tests, refactoring code, or improving test coverage. Covers pytest, unittest, and mock strategies.

Tool/Framework Skills

Pattern:

Guides [tool/framework] [specific use] with [approaches]. Use when [scenarios]. Covers [features].

Example:

description: Guides FastAPI development with async patterns, dependency injection, and OpenAPI documentation. Use when building REST APIs, implementing async endpoints, or generating API docs. Covers Pydantic models, authentication, and testing.

Review/Audit Skills

Pattern:

Analyzes [target] for [qualities]. Use when [review scenarios]. Checks [specific items].

Example:

description: Analyzes API security for authentication, validation, and error handling compliance. Use when reviewing endpoints, auditing security practices, or preparing for deployment. Checks OAuth flows, input sanitization, and rate limiting.

Pattern/Practice Skills

Pattern:

Implements [pattern/practice] for [outcome]. Use when [scenarios]. Follows [standards].

Example:

description: Implements repository pattern for data access layer separation. Use when designing database interactions, refactoring data access code, or implementing clean architecture. Follows DDD principles and SOLID design.

Common Mistakes

1. First Person Voice

Wrong:

description: I help you write better commit messages using conventional commits.

Correct:

description: Guides commit message writing using conventional commits standard. Use when committing changes, reviewing git history, or establishing commit conventions.

2. Marketing Language

Wrong:

description: The ultimate, detailed, enterprise-grade solution for all your testing needs! Revolutionary approach that will transform your development workflow!

Correct:

description: Guides test-driven development using RED-GREEN-REFACTOR methodology. Use when writing tests, refactoring code, or improving coverage. Covers unit, integration, and end-to-end testing.

3. Missing "Use When"

Wrong:

description: Provides API security guidelines and best practices for authentication and validation.

Correct:

description: Provides API security guidelines for authentication and input validation. Use when designing endpoints, reviewing security, or implementing access controls. Covers OAuth, JWT, and rate limiting.

4. Too Technical

Wrong:

description: Implements CQRS/ES architectural pattern with event sourcing, domain events, aggregate roots, and eventual consistency patterns for distributed systems using message brokers.

Better:

description: Guides CQRS and event sourcing architecture for scalable systems. Use when designing command/query separation, implementing event-driven patterns, or building distributed applications. Covers aggregates, events, and consistency.

5. No Discovery Terms

Wrong:

description: Helps with code organization and structure improvements.

Better:

description: Guides code refactoring for improved structure and maintainability. Use when cleaning up legacy code, applying SOLID principles, or reducing technical debt. Covers extract method, dependency injection, and module organization.

A/B Testing Descriptions

Methodology

1. Create two versions of description 2. Test discovery with 10+ varied queries 3. Count how many queries successfully activate skill 4. Choose version with higher activation rate

Example Test

Version A:

description: Helps with Python testing.

Version B:

description: Guides Python testing using pytest and unittest frameworks. Use when writing tests, debugging test failures, or improving coverage. Covers fixtures, mocks, and parametrization.

Test Queries: 1. "Add tests for this Python function" 2. "How do I test async Python code" 3. "Set up pytest for my project" 4. "Mock external API in tests" 5. "Improve test coverage"

Results:

• Version A: 2/5 activations (40%)
• Version B: 5/5 activations (100%)

Validation Checklist

Before finalizing a description:

• [ ] Uses third person voice
• [ ] Includes "Use when..." clause
• [ ] Has 3+ specific use cases
• [ ] Contains relevant discovery terms
• [ ] Length is 200-400 characters
• [ ] Avoids marketing language
• [ ] Specifies what skill does (not just domain)
• [ ] Distinguishes from similar skills
• [ ] Uses active, specific verbs
• [ ] Would match user's natural language

Tools

Character Counter

# Count description length
echo "Your description here" | wc -c

Discovery Term Extraction

def extract_discovery_terms(description: str) -> list[str]:
    """Extract potential discovery keywords from description."""
    # Common stop words to exclude
    stop_words = {'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for'}

    # Split and filter
    words = description.lower().split()
    terms = [w.strip('.,!?;:') for w in words
             if w not in stop_words and len(w) > 3]

    return sorted(set(terms))

A/B Test Template

## Description A/B Test

### Version A

description: [First version]

### Version B

description: [Second version]

### Test Queries
1. [Common user query 1]
2. [Common user query 2]
...

### Results
| Query | Version A | Version B |
|-------|-----------|-----------|
| Q1    | OK/FAIL       | OK/FAIL       |
| Q2    | OK/FAIL       | OK/FAIL       |

**Winner**: Version [A/B] ([X]% activation rate)

Summary

Effective descriptions: 1. Third person voice: "Guides...", "Teaches...", "Implements..." 2. Include "Use when": Explicit activation conditions 3. Key discovery terms: Match user language patterns 4. 200-400 characters: Specific but concise 5. Active verbs: Clear action orientation 6. Specific use cases: Concrete scenarios, not vague domains

Formula: [WHAT] + [WHEN] + [KEY TERMS]

Test with real queries to validate discoverability.

Error Handling in Skills

Skills run in environments that fail in many ways: tools missing, commands timing out, partial subagent results, network errors, permission denials. This module covers how the SKILL.md should direct Claude when failures occur. The goal is a skill that fails loudly and recoverably rather than one that drifts into hallucinated success.

Three failure surfaces

A skill must handle errors at three layers. Conflating them produces skills that catch the wrong thing or paper over real problems.

Tool failures

The most common failure. A shell command exits non-zero, an MCP tool returns an error payload, a script raises. Claude tends to narrate around the error ("I'll try a different approach") and proceeds without the data the next step needs.

Pattern: surface, stop, ask

In SKILL.md, write the rule explicitly:

## Tool Failures

When a tool returns a non-zero exit or an error payload:

1. Print the exit code and stderr verbatim (no paraphrasing).
2. Stop the workflow. Do not attempt the next step.
3. Tell the user what failed and what input would let you
   recover. Wait for the user to respond.

Do not "try a different approach" silently. Do not retry the
same command with different arguments unless the error message
explicitly suggests an argument fix.

This blocks the most expensive rationalization: Claude deciding that a failure is "minor" and continuing into a state where the next failure is much more expensive to diagnose.

Pattern: classify before reacting

For skills that handle a class of tool failures (e.g., git operations), include a classification table:

## Git Failure Classes

| Error pattern | Class | Action |
|---------------|-------|--------|
| `nothing to commit` | benign | Report, continue |
| `merge conflict` | user-input | Stop, ask user to resolve |
| `permission denied` | auth | Stop, see authentication.md |
| `repository not found` | config | Stop, ask for correct remote |

Without classification, every error becomes a stop, which is safe but noisy. With classification, the skill stops only when human input is required.

Missing dependencies

Skills that ship scripts often assume uv, python3.11+, ripgrep, or specific MCP servers are installed. When a dependency is missing, the failure surface is:

1. Script invocation fails with command not found or ModuleNotFoundError. 2. Claude reads the error and tries to install the dependency. 3. Install fails for an unrelated reason (no sudo, wrong python). 4. Two failures stacked, neither diagnosed.

Pattern: declare and verify

Declare dependencies in the skill frontmatter or an opening section, and have the skill verify them before any work:

## Dependencies

This skill requires:
- `python3` 3.11 or later (`python3 --version`)
- `ripgrep` (`rg --version`)
- `gh` (`gh --version`)

Run the verification step first. If any check fails, stop and
print the install command for the user's platform. Do not
attempt to install dependencies on the user's behalf.

The "do not attempt to install" line is critical. Auto-install chains hide the actual problem (wrong PATH, missing sudo, wrong package manager) behind a more confusing failure.

Pattern: graceful degradation when optional

Some dependencies are optional. State which features require which dependency, and fall back cleanly:

## Optional Dependencies

- `sem` (semantic diff): if missing, the skill skips semantic
  analysis and falls back to plain `git diff`. Print a notice
  ("sem not installed, using git diff") rather than continuing
  silently.

The notice matters. Silent fallback degrades skill output quality without telling the user why.

Partial failures

The hardest class. A subagent dispatched to do five things returns three with results, one with a stub, and one with a plausible-sounding fabrication. Or a parallel review returns six findings out of an expected ten.

Pattern: explicit completion contract

Skills that dispatch subagents should require an explicit completion signal:

## Subagent Completion Contract

Every dispatched subagent must end its output with one of:

- `STATUS: COMPLETE` (all assigned work done with evidence)
- `STATUS: PARTIAL <reason>` (some work blocked, reason given)
- `STATUS: FAILED <reason>` (work not attempted, reason given)

If a subagent returns without one of these markers, treat the
result as `STATUS: UNKNOWN`. Do not merge unknown results into
the final output. Re-dispatch or escalate to the user.

The marker forces the subagent to commit to a state. Without it, partial output looks identical to complete output.

Pattern: count and verify

For dispatches with known cardinality (six findings, ten files), verify the count before treating the result as complete:

## Result Verification

After parallel dispatch, count the returned items:

- Expected: 10 file analyses
- Received: count the items in each response

If received < expected, list the missing items by name and
re-dispatch only those. Do not produce a final summary from a
short result.

This catches the failure mode where a subagent returns a summary like "I analyzed all the files" with five entries.

Anti-patterns

These patterns look like error handling but degrade behavior.

Catch-all rescue

## Error Recovery

If anything fails, try the alternative approach in
modules/<fallback-name>.md.

This trains Claude to swallow errors. Every failure becomes a detour into the fallback module, hiding the original problem. Specify which error classes route to which fallback.

Helpful retries

## Retry Policy

If a tool fails, retry up to 3 times before reporting.

For idempotent reads (a gh api GET), one retry is reasonable. For state-changing operations (commits, pushes, file writes), silent retries cause duplicate work or corrupt state. Default to no retry. Add retries only for specific commands with documented idempotence.

Best-effort completion

## Partial Results

If some steps fail, continue with the steps that succeeded and
report the failures at the end.

This produces output that looks complete but is missing the parts the user actually needed. Stop on the first failure unless the skill explicitly handles partial results with a known recovery path.

Error paraphrase

When a command fails, summarize the error in plain language for
the user.

Paraphrased errors lose the diagnostic strings (line numbers, exit codes, error class names) the user needs to debug. Print the raw error first, then add context if needed.

Verification

Add baseline tests for each failure surface:

Tool failure: run the skill against a repo where `gh auth status`
returns exit 1. Expected: skill stops, surfaces the error.
Failure: skill paraphrases the error or proceeds.

Missing dependency: rename `rg` out of PATH and run the skill.
Expected: skill stops at the dependency check, prints install
command. Failure: skill silently uses `grep` or hallucinates rg
output.

Partial result: dispatch a subagent that returns three of five
findings. Expected: skill reports incomplete and re-dispatches
or escalates. Failure: skill produces a summary as if all five
were received.

Cross-reference: see Skill(leyline:error-patterns) for the shared error classification taxonomy reused across plugins, and Skill(superpowers:systematic-debugging) for the diagnosis methodology applied to skill failures.

Annotated Examples of Well-Authored Skills

Annotated walk-throughs of skills that ship in this repo. Each example highlights one or two authoring decisions worth copying. Read these after tdd-methodology.md and progressive-disclosure.md. Citations are to real files; you can Read any path below to see the full source.

Example 1: a focused technique skill

Skill: Skill(superpowers:test-driven-development) Path: not in this repo (ships from a separate marketplace) What it does: enforces the red/green/refactor cycle for implementation work.

This skill is worth studying for one reason: the description field uses the formula WHAT + WHEN + TRIGGERS and earns its activation rank without any keyword stuffing. The skill loads when the user says "implement X" or "fix bug Y" and stays out of the way otherwise.

The lesson: a skill with one job, named after that job, with a description that names the job again, will activate reliably.

Example 2: a tiered audit skill

Skill: Skill(pensive:tiered-audit) Path: /home/alext/claude-night-market/plugins/pensive/skills/tiered-audit/SKILL.md

What to copy from this skill:

1. Explicit escalation tiers. The skill defines Tier 1 (git history), Tier 2 (targeted deep-dive), and Tier 3 (full codebase). Each tier names what it costs and what it produces. The user (or the orchestrator) picks the tier.

2. Default to the cheapest tier. The skill says "default to Tier 1" and requires explicit approval to escalate. This counters the rationalization "I'll do a thorough job by running Tier 3 just in case." See anti-rationalization.md.

3. Output contract per tier. Tier 1 produces a different artifact than Tier 3. The skill names both. The reader knows what to expect before paying the cost.

The pattern generalizes: any skill with a cost gradient (quick/thorough, local/global, draft/final) should expose tiers explicitly rather than letting Claude pick.

Example 3: a TDD-for-skills meta-skill

Skill: Skill(abstract:subagent-testing) Path: /home/alext/claude-night-market/plugins/abstract/skills/subagent-testing/SKILL.md

This skill exists because skill-authoring requires baseline tests in fresh subagents. Rather than restating the testing methodology in every skill that needs it, skill-authoring defers to this skill.

What to copy:

1. Single-purpose deference. skill-authoring/SKILL.md contains one line: "Testing with Subagents: See abstract:subagent-testing skill for pressure testing methodology." That is the right amount. The testing skill owns the testing content.

2. Token budget declared. The frontmatter sets token_budget: 30, signaling the skill itself is small. Most of its content is in the subagent-testing skill's testing-patterns module, loaded only when needed.

3. Hub Table of Contents. The hub starts with a TOC. For skills above 100 lines, the TOC pays for itself in navigation. The skills-eval rubric penalizes skills above 100 lines that lack one (see evaluation-criteria.md).

Example 4: an enforcement skill

Skill: Skill(imbue:proof-of-work) Path: /home/alext/claude-night-market/plugins/imbue/skills/proof-of-work/SKILL.md

This skill enforces evidence before "done." It is referenced by skill-authoring/SKILL.md as the source of detailed enforcement patterns: "Detailed enforcement patterns for adversarial verification and coverage gates are available in imbue:proof-of-work."

What to copy:

1. Negative space. The skill is mostly about what completion claims to refuse. The positive content (what counts as evidence) takes less room than the refusals. This matches how Claude actually fails. It rarely fails to do work; it fails to verify the work it did.

2. Explicit acceptance criteria template. The skill provides a template the user can paste into any acceptance-criteria document. Templates outperform exhortation: "use these criteria" works better than "be thorough about acceptance."

3. Cross-plugin reuse. proof-of-work is referenced from abstract:skill-authoring, sanctum:do-issue, and egregore:quality-gate. Skills designed to be called by other skills should keep their interface narrow. This skill exposes a small set of named patterns rather than a single monolithic procedure.

Example 5: a slop-detection skill

Skill: Skill(scribe:slop-detector) Path: /home/alext/claude-night-market/plugins/scribe/skills/slop-detector/SKILL.md

What to copy:

1. Sub-modules as the unit of recommendation. The skill exposes wrapping-rules, identity-and-voice-leaks, hallucination-detection, and others as nameable modules. Other documents reference specific modules (Skill(scribe:slop-detector) module document-economy.md) rather than the whole skill. This makes the skill composable.

2. Detection commands paired with fixes. Each pattern in the skill comes with a command (grep -o '—' file.md | wc -l) and a fix. The reader is not left with "find slop"; they are given a way to find it and a way to fix it.

Example 6: a structural skill graph audit

Skill: Skill(abstract:skill-graph-audit) Path: /home/alext/claude-night-market/plugins/abstract/skills/skill-graph-audit/SKILL.md

What to copy:

1. Operates on the corpus, not on a single skill. Skills that audit the skill graph itself need a different shape: they take a directory, walk it, and emit a report. The skill makes this explicit in its description: "Map Skill() refs across plugins; detect hubs, isolates, and dangling targets."

2. Output is data, not prose. The skill produces a graph structure other tools can consume, rather than a narrative only humans can read. Skills that produce machine-readable output multiply in value when chained.

What every example has in common

Anti-pattern: the kitchen-sink skill

A real example, anonymized: a skill named development-best-practices with a 3,200-line SKILL.md covering testing, deployment, security, performance, and documentation. Activation was unreliable (the description matched everything and nothing). Token cost was high (every load pulled the entire file). Nobody could safely edit it (a change to the testing section risked breaking the deployment section).

The fix was to split it into five focused skills, each with its own description and frontmatter. Activation rank improved on every measured query. Token cost on initial load dropped by 80%. Edits became localized.

Lesson: when in doubt, split. A skill is the wrong unit if it needs more than one paragraph to describe its job.

Verification

To check that an example you are copying is still current:

# Confirm the skill exists at the path
ls plugins/<plugin>/skills/<skill>/SKILL.md

# Confirm the description still matches the example
head -10 plugins/<plugin>/skills/<skill>/SKILL.md

# Run the skills-eval auditor against the example
python plugins/abstract/scripts/skills_auditor.py \
  --skill plugins/<plugin>/skills/<skill>/SKILL.md

If a skill cited above has changed shape, update this module rather than copying an outdated pattern.

Cross-reference: see Skill(abstract:skill-graph-audit) for the corpus-level view of how these skills reference each other and where the hubs and isolates live.

Graphviz Conventions for Skill Diagrams

Process diagrams help visualize skill workflows, decision trees, and error handling.

When to Include Diagrams

Use diagrams for:

• Complex decision trees (3+ decision points)
• Multi-step workflows with branches
• Error handling flows
• State transitions

Skip diagrams for:

• Simple linear workflows (use numbered lists)
• Single decision points
• Purely conceptual relationships (use tables)

Node Type Conventions

Quick Reference

Decision Node

node [shape=diamond]
decision [label="Tests\nexist?"]

Action Node

node [shape=box]
action [label="Run tests"]

Command Node

node [shape=plaintext, fontname="Courier"]
cmd [label="pytest tests/"]

Edge Labels

Layout Settings

// Top to bottom (default)
rankdir=TB

// Left to right (sequential)
rankdir=LR

Semantic Colors

Validation Checklist

• [ ] Decision nodes are diamonds with questions
• [ ] Action nodes are boxes with verbs
• [ ] Binary decisions use "yes"/"no"
• [ ] Colors are semantic and accessible
• [ ] Text wraps at 10-15 characters
• [ ] Diagram adds value beyond text

Rendering

dot -Tsvg workflow.dot -o workflow.svg  # Recommended
dot -Tpng workflow.dot -o workflow.png

Detailed Examples

For complete examples including:

• Full TDD workflow diagram
• Subgraph grouping patterns
• State machine examples
• Error handling flows
• Anti-patterns to avoid

Use dot -Tsvg workflow.dot -o workflow.svg to render diagrams locally.

Persuasion Principles for Skill Design

Overview

Skills are behavioral interventions. Research shows that incorporating compliance psychology principles can dramatically improve adherence rates. This module covers evidence-based persuasion techniques for skill design.

Research Foundation

Meincke et al. (2025): Persuasion Doubles Compliance

Study: Persuasive Paraphrasing in Large Language Models

Key Finding: Incorporating persuasion principles into instructions doubled compliance rates:

• Baseline: 33% compliance with standard instructions
• Persuasive: 72% compliance with persuasion-enhanced instructions
• Improvement: 118% increase (more than doubled)

Implication: How you phrase requirements dramatically affects whether Claude follows them.

Six Principles of Persuasion (Cialdini)

The study validated Cialdini's classic persuasion principles in LLM contexts:

1. Authority: Directive language from credible sources 2. Commitment & Consistency: Explicit declarations and progressive commitment 3. Scarcity: Time-bound requirements and limited exceptions 4. Social Proof: Universal norms and common practices 5. Liking: Collaborative language and shared goals 6. Unity: In-group language and shared identity

Application to Skill Design

1. Authority

Principle: Claude responds to authoritative, directive language

Implementation:

 Weak (Suggestive):
"Consider adding input validation to your API endpoints."

 Strong (Authoritative):
"MUST include input validation on every API endpoint."

 Stronger (Imperative + Reason):
"Every API endpoint MUST validate all inputs. This is a
foundational security requirement to prevent injection attacks."

When to Use:

• Safety-critical practices (security, correctness)
• Non-negotiable requirements
• Preventing known failure modes

When to Moderate:

• Stylistic preferences
• Optimization suggestions
• Context-dependent choices

2. Commitment & Consistency

Principle: Explicit commitment creates pressure to follow through

Implementation:

## Before Starting

Declare out loud:
"I am using the secure-api-design skill to validate complete
security coverage regardless of time pressure or scope."

## During Work

At each decision point, ask:
"Am I following the skill requirements, or am I finding
reasons to bypass them?"

## After Completion

Verify explicitly:
"I have applied ALL security requirements. No exceptions
were taken without explicit user approval."

Progressive Commitment:

## Skill Activation Checklist

I commit to:
- [ ] Reading ALL requirements before starting
- [ ] Applying requirements to THIS specific task
- [ ] Not taking shortcuts based on "simplicity"
- [ ] Asking for clarification rather than assuming exceptions

Effectiveness: Creates cognitive dissonance when Claude tries to bypass requirements after explicitly committing.

3. Scarcity

Principle: Limited availability or time-bound requirements increase urgency

Implementation:

 Weak (Open-ended):
"Authentication should be added to APIs at some point."

 Strong (Immediate):
"Authentication MUST be included in the initial implementation.
Adding it later requires refactoring and creates security gaps."

 Stronger (Scarcity + Consequence):
"Authentication MUST be included NOW. Every minute without
auth is a security exposure. 'Adding it later' has 80% failure
rate in production systems."

Time-Bound Language:

• "Before proceeding..."
• "In this implementation..."
• "Now, not later..."
• "Every time, without exception..."

4. Social Proof

Principle: Claude follows practices framed as universal or standard

Implementation:

 Weak (Isolated):
"Input validation is important."

 Strong (Universal):
"Every production API validates inputs. This is a universal
security baseline across all modern systems."

 Stronger (Consensus + Statistics):
"97% of API security breaches involve inadequate input validation.
Every major framework (Django, Rails, Spring) validates by default.
Industry consensus: validation is non-negotiable."

Normative Language:

• "Every [role] does X"
• "Industry standard requires..."
• "Universal practice is..."
• "Consistent across all major..."

5. Liking (Collaborative Language)

Principle: Cooperative framing increases compliance

Implementation:

 Weak (Adversarial):
"You must follow these rules or your code will be insecure."

 Strong (Collaborative):
"Together, we'll validate this API meets security standards.
Following these requirements protects users and prevents
common vulnerabilities."

 Stronger (Shared Goals):
"We both want secure, reliable code. These requirements
represent collective wisdom from thousands of security incidents.
They help us avoid repeating others' mistakes."

Collaborative Patterns:

• "We" language (we're building, we need to...)
• Shared objectives (protect users, prevent issues)
• Learning frame (avoid others' mistakes)

6. Unity (Shared Identity)

Principle: In-group language strengthens compliance

Implementation:

 Weak (Generic):
"Developers should write tests."

 Strong (In-group):
"Professional developers write tests. It's part of our craft."

 Stronger (Identity + Pride):
"As engineers who take pride in our work, we write
detailed tests. This is what separates professionals
from amateurs. Our code reflects our values."

Identity Language:

• "As [professional role]..."
• "Part of our craft/discipline"
• "What separates us from..."
• "Our standards require..."

Combining Principles

Most effective skills combine multiple principles:

## Test-Driven Development

### Commitment (Before Starting)
Declare: "I am following TDD. Tests come first, every time."

### Authority + Social Proof
Professional developers write tests before implementation.
This is the industry standard for quality software.
TDD is practiced at Google, Amazon, Microsoft, and every
major technology company.

### Scarcity
Write the test NOW. Every line of untested code is
technical debt. "Testing later" fails 90% of the time.

### Unity
As engineers who value quality, we write tests first.
This is what separates professional development from
scripting. Our craft demands this discipline.

### Consistency Check
Before writing ANY implementation code, ask:
"Have I written a failing test first?"

If no: Stop. Write test first.

Ethical Considerations

When Persuasion Is Appropriate

Use persuasive techniques for:

• Safety-critical practices: Security, correctness, data integrity
• Empirically-validated best practices: TDD, code review, testing
• Preventing documented failure modes: Known antipatterns, common mistakes
• User-requested rigor: When user wants enforced discipline

When to Dial It Back

[WARN] Moderate persuasion for:

• Stylistic preferences: Formatting, naming, organization
• Context-dependent choices: Performance vs. readability trade-offs
• Emerging practices: New patterns without long track record
• Optimization suggestions: Nice-to-have improvements

The Ethical Test

Ask: "Would this serve the user's genuine interests?"

Ethical:

"Every API endpoint MUST validate inputs. This protects
users from injection attacks and data corruption."

Rationale: Prevents real harm, serves user security interests

Unethical:

"You MUST use tabs for indentation. Spaces are objectively
wrong and used only by inferior developers."

Rationale: Arbitrary preference, shame-based, no real benefit

Transparency Principle

Skills should be transparent about their persuasive intent:

## About This Skill

This skill uses directive language and commitment techniques
to validate security requirements are never skipped under time
pressure. The authoritative tone is intentional: security
breaches are permanent, while code can be refactored.

If you need flexibility (prototypes, exploration), explicitly
state that security can be deferred. Otherwise, this skill
assumes production-quality requirements.

Persuasion Patterns Library

Pattern: The Exception Table

Purpose: Block rationalizations by explicitly listing exceptions

## When This Requirement Does NOT Apply

| Scenario | Required? | Rationale |
|----------|-----------|-----------|
| Production code | OK Always | Security non-negotiable |
| Internal tools | OK Always | Common attack vector |
| Prototypes | OK Always | Become production |
| "Simple" endpoints | OK Always | Complexity ≠ security need |
| Time pressure | OK Always | Breaches are permanent |
| Trusted users | OK Always | Users make mistakes |

**No exceptions**. The only valid exception is explicit user
statement: "Skip security for [specific reason]."

Pattern: The Red Flags List

Purpose: Create self-checking mechanism

## Red Flags That You're Rationalizing

Stop immediately if you think:
- "This is too simple for full security"
- "We can add validation later"
- "Trusted users don't need this"
- "Time pressure justifies shortcuts"
- "Internal API, lighter requirements"

These are rationalizations, not valid exceptions.
Return to skill requirements.

Pattern: The Commitment Declaration

Purpose: Create cognitive dissonance for future bypassing

## Activation Declaration

Before starting, declare out loud:

"I am using [skill name] for this task.
I will apply ALL requirements.
I will not take shortcuts based on:
- Time pressure
- Perceived simplicity
- Scope assumptions
- Personal confidence

If I think an exception applies, I will ask the user first."

Pattern: The Consequence Chain

Purpose: Connect requirement to real outcomes

## Why This Requirement Exists

Input validation prevents:
→ SQL injection attacks
→ Cross-site scripting (XSS)
→ Remote code execution
→ Data corruption
→ System compromise

Skipping validation because "this is simple" means:
→ Vulnerability exists from day 1
→ Exploit takes minutes to write
→ Breach costs average $4.35M
→ Your career reputation suffers

Is "saving 10 minutes" worth that risk?

Pattern: The Universal Standard

Purpose: use social proof

## Industry Standard

Every major framework validates inputs by default:
- Django: Form validation required
- Rails: Strong parameters enforced
- Spring: Bean validation standard
- Express: Validator middleware common

This is the baseline professional standard, not an option.
Custom APIs that skip validation are security incidents
waiting to happen.

Adaptation for Claude 4.x

Research from 2025 used Claude 3.x models. Claude 4.x (Opus, Sonnet) may require adjustments:

Observed Differences

Claude 3.x: Benefits from strong directive language Claude 4.x: May be oversensitive to aggressive tone

Recommended Adjustments

 Too Aggressive for 4.x:
"You MUST NEVER skip validation. This is NON-NEGOTIABLE."

 Adjusted for 4.x:
"Every endpoint requires input validation. This is a
foundational security requirement with no exceptions."

 Too Aggressive:
"STOP. You're rationalizing. This is a red flag."

 Adjusted:
"Check: Is this a valid exception or rationalization?
Review the exception table before proceeding."

Principle: Firm but Professional

• Maintain authority without aggression
• Use "required" over "MUST" when tone matters
• Keep consequences factual, not emotional
• Preserve commitment patterns (still effective)

Testing Persuasion Effectiveness

Metrics

1. Compliance Rate: % of times requirement followed 2. Rationalization Attempts: Frequency of excuse-making 3. Recovery Rate: % of times Claude self-corrects 4. User Override: % of times user must intervene

A/B Testing Framework

## Version A: Neutral Language
"Consider adding input validation to protect against
injection attacks."

## Version B: Persuasive Language
"Every endpoint MUST validate inputs. This is a universal
security baseline that prevents injection attacks."

## Test Results (10 scenarios each)
- Version A: 4/10 compliance (40%)
- Version B: 9/10 compliance (90%)
- Improvement: 125%

Summary

Effective persuasion in skills:

1. Authority: Use directive language for safety-critical requirements 2. Commitment: Force explicit declarations before starting 3. Scarcity: Frame requirements as immediate, not deferred 4. Social Proof: use universal standards and consensus 5. Liking: Use collaborative language and shared goals 6. Unity: Appeal to professional identity and values

Ethical guideline: Persuasion should serve user interests, not arbitrary preferences.

Evidence: Persuasive framing can double compliance rates (33% → 72%).

Adjustment: Dial back aggressive language for Claude 4.x while preserving firm requirements.

Progressive Disclosure for Token Efficiency

Overview

Progressive disclosure structures skills so Claude loads only what's needed when it's needed. This keeps context windows efficient while maintaining detailed functionality.

Core Principle

SKILL.md is the table of contents, not the encyclopedia.

• Main file provides overview and entry points
• Detailed content is in separate files
• Claude loads details only when needed
• Keeps initial context small and focused

File Structure Pattern

Hub-and-Spoke Model

skill-name/
├── SKILL.md              # Hub: 300-500 lines
├── modules/              # Spokes: detailed content
│   ├── concept-1.md
│   ├── concept-2.md
│   └── advanced-patterns.md
└── scripts/              # Tools: executable utilities
    └── validator.py

SKILL.md contains:

• Frontmatter (YAML)
• Overview (what/why)
• Quick start (minimal example)
• When to use (activation conditions)
• Common tasks (high-level)
• Module references (links to details)

Modules contain:

• Deep dives on specific topics
• Advanced techniques
• Edge cases and troubleshooting
• Detailed examples

Scripts contain:

• Executable validation
• Analysis tools
• Automation utilities

Line Count Guidelines

SKILL.md Target: Under 500 Lines

Rationale:

• Entire skill loads in ~600 tokens
• Quick to scan and understand
• Minimal initial context consumption
• Forces focus on essential information

What to Keep:

• Required frontmatter
• Core concepts overview
• Single minimal example
• High-level workflow
• Module references

What to Move:

• Detailed explanations → modules
• Additional examples → modules
• Edge cases → modules
• Troubleshooting → modules
• Tool documentation → scripts/README.md

Module Target: 200-400 Lines Each

Rationale:

• Focused on single topic
• Loaded only when needed
• Still readable in one sitting
• Easy to maintain and update

Structure:

• Clear topic focus
• Progressive complexity
• Examples throughout
• Cross-references minimal

Reference Depth: One Level Only

The Rule

SKILL.md can reference modules. Modules should NOT reference other modules extensively.

Why

Problem with deep references:

SKILL.md → module-a.md → module-b.md → module-c.md

Claude must load entire chain to understand context. Defeats progressive disclosure purpose.

Better approach:

SKILL.md → module-a.md
SKILL.md → module-b.md
SKILL.md → module-c.md

Each module stands alone. Load only what's needed for current task.

Exception: Shared Resources

Acceptable to reference shared utilities:

modules/
├── core-concepts.md      # Referenced by SKILL.md
├── advanced-patterns.md  # References core-concepts for foundation
└── troubleshooting.md    # References both above for context

Guideline: If a module needs >2 other modules to make sense, restructure it.

Content Distribution Strategy

What Goes in SKILL.md

1. The 80/20 Content

Cover 80% of use cases with 20% of content:

## Quick Start

Most common workflow:
1. Run baseline tests
2. Write minimal skill
3. Validate improvements

For advanced scenarios, see modules:
- Complex workflows: `modules/advanced-patterns.md`
- Troubleshooting: `modules/troubleshooting.md`

2. High-Level Overview

Conceptual understanding without implementation details:

## Core Concept

Skills use TDD methodology:
- RED: Document failures
- GREEN: Minimal fix
- REFACTOR: Bulletproof

For detailed RED phase process, see `modules/tdd-methodology.md`

3. One Complete Example

Single end-to-end example showing typical usage:

## Example: Secure API Skill

1. Document baseline (3 scenarios)
2. Write skill addressing failures
3. Add anti-rationalization

For additional examples, see `modules/examples.md`

4. Common Tasks Overview

High-level task list with module pointers:

## Common Tasks

- **Creating new skill**: See "Quick Start" above
- **Optimizing descriptions**: See `modules/description-writing.md`
- **Bulletproofing**: See `modules/anti-rationalization.md`

What Goes in Modules

1. Deep Dives

detailed coverage of specific topics:

# TDD Methodology for Skills

## RED Phase: Complete Guide

### Designing Pressure Scenarios

Create scenarios combining:
1. Time pressure ("quickly")
2. Ambiguity ("standard approach")
3. Multiple requirements
4. Edge cases

[... detailed examples and analysis ...]

2. Advanced Techniques

Beyond basic usage:

# Advanced Patterns

## Multi-Skill Composition

When skills need to work together:
[... detailed composition strategies ...]

## Conditional Loading

Load modules based on context:
[... conditional logic examples ...]

3. Edge Cases and Troubleshooting

Specific problems and solutions:

# Troubleshooting

## Skill Not Activating

Symptoms:
- Claude doesn't load skill for relevant tasks
- Activation is inconsistent

Causes:
1. Description too generic
2. Missing discovery terms
3. Competing skills

Solutions:
[... detailed debugging steps ...]

4. Extended Examples

Additional real-world scenarios:

# Example Gallery

## Example 1: Security Skill

Complete TDD cycle for API security:
[... full detailed example ...]

## Example 2: Testing Skill

[... another complete example ...]

Progressive Complexity Pattern

Structure content from simple to complex:

SKILL.md: Entry Level

## Quick Start

1. Document failures
2. Write skill
3. Test improvements

See modules for details.

Module: Intermediate

# TDD Methodology

## Basic Approach

1. Create 3 pressure scenarios
2. Run without skill
3. Document failures verbatim

## Scenario Design

Combine these factors:
- Time pressure
- Ambiguity
- Multiple requirements

[... examples and guidance ...]

Module Section: Advanced

## Advanced Scenario Design

### Multi-Factor Pressure

Combine 4+ challenge factors:
[... sophisticated examples ...]

### Adversarial Testing

Design scenarios to trigger specific rationalizations:
[... advanced techniques ...]

Loading Patterns

Explicit References

Make module references clear and actionable:

Good:

For detailed description optimization techniques,
see `modules/description-writing.md`

Vague:

More information is available in the modules directory.

Just-In-Time Loading

Structure so Claude loads modules when needed:

## Common Tasks

### Task 1: Create New Skill
[Brief inline guidance]

### Task 2: Optimize Discovery
This requires understanding description patterns.
See `modules/description-writing.md` for:
- Discovery term selection
- "Use when" clause structure
- A/B testing methodology

Lazy Evaluation

Don't force module loading upfront:

Eager Loading (avoid):

Before using this skill, read all modules:
- modules/tdd-methodology.md
- modules/persuasion-principles.md
- modules/anti-rationalization.md

Lazy Loading (preferred):

Start with Quick Start below.
Reference modules as needed for specific tasks.

Token Budgeting

Estimation Formula

Total tokens = SKILL.md + (loaded modules) + (context overhead)

Target budgets:

• SKILL.md: ~600 tokens (500 lines)
• Module: ~300-500 tokens each (200-400 lines)
• Context overhead: ~200 tokens
• Initial load: ~800 tokens
• With 1 module: ~1,300 tokens
• With 3 modules: ~2,300 tokens

Optimization Strategies

1. Defer Examples

One example in SKILL.md, more in modules:

estimated_tokens: 800  # SKILL.md only

# In modules/examples.md
estimated_tokens: 1200  # All examples

2. Split Large Topics

Instead of one 800-line module:

modules/
├── core-concepts.md      # 300 lines
├── advanced-patterns.md  # 300 lines
└── troubleshooting.md    # 200 lines

3. Compression Techniques

Use tables instead of prose:

Verbose (20 lines):

The first principle is Authority. This means using
directive language. For example, instead of saying
"consider adding validation," say "must add validation."
This is because...

Compressed (5 lines):

| Principle | Weak | Strong |
|-----------|------|--------|
| Authority | "Consider validation" | "Must validate" |

File Organization Examples

Example 1: TDD Skill

tdd-workflow/
├── SKILL.md (450 lines)
│   ├── Overview
│   ├── Quick Start
│   ├── Common Tasks
│   └── Module References
└── modules/
    ├── red-phase.md (350 lines)
    ├── green-phase.md (300 lines)
    ├── refactor-phase.md (300 lines)
    └── examples.md (400 lines)

Total: 1,800 lines Initial load: 450 lines Typical usage: 450 + 350 = 800 lines Full exploration: All 1,800 lines

Example 2: Security Skill

secure-api/
├── SKILL.md (400 lines)
│   ├── Core Requirements
│   ├── One Example
│   └── Module Links
└── modules/
    ├── authentication.md (300 lines)
    ├── validation.md (250 lines)
    ├── error-handling.md (200 lines)
    └── advanced-threats.md (350 lines)

Total: 1,500 lines Initial load: 400 lines Task-specific: 400 + 300 = 700 lines

Example 3: Monolithic (Anti-Pattern)

Don't do this:

skill-name/
└── SKILL.md (1,500 lines)
    ├── Everything in one file
    ├── All examples
    ├── All edge cases
    └── All troubleshooting

Problem: Always loads 1,500 lines even for simple tasks

Refactoring Monolithic Skills

Process

1. Identify Sections in current SKILL.md 2. Categorize:

• Essential (keep in SKILL.md)
• Detailed (move to modules)
• Reference (move to modules)

3. Extract Modules with focused topics 4. Update References in SKILL.md 5. Test to validate coherence

Example Refactoring

Before (1,000 lines):

# API Security

## Overview
[100 lines]

## Authentication Deep Dive
[300 lines]

## Validation Techniques
[250 lines]

## Error Handling
[200 lines]

## Examples
[150 lines]

After (400 and modules):

# API Security (SKILL.md - 400 lines)

## Overview
[100 lines]

## Core Requirements
[150 lines]

## Quick Example
[50 lines]

## Detailed Topics
- Authentication: `modules/authentication.md`
- Validation: `modules/validation.md`
- Error Handling: `modules/error-handling.md`
- Examples: `modules/examples.md`

# modules/authentication.md (300 lines)
[Detailed authentication content]

# modules/validation.md (250 lines)
[Detailed validation content]

# modules/error-handling.md (200 lines)
[Detailed error handling content]

# modules/examples.md (150 lines)
[All examples]

Validation

Checklist

• [ ] SKILL.md under 500 lines
• [ ] Each module 200-400 lines
• [ ] Module references one level deep
• [ ] Clear loading path (when to read modules)
• [ ] No circular references
• [ ] Examples progressively complex
• [ ] Quick start doesn't require modules
• [ ] Module topics focused and distinct
• [ ] estimated_tokens in frontmatter accurate

Tool

# Check line counts
wc -l SKILL.md modules/*.md

# Validate structure
python scripts/skill_validator.py --check-structure

Summary

Progressive disclosure principles: 1. SKILL.md is the hub (under 500 lines) 2. Modules are spokes (200-400 lines each) 3. One level deep (avoid deep reference chains) 4. Load on demand (don't force eager loading) 5. Progressive complexity (simple → advanced) 6. Token budgeting (~800 initial, ~1,500 with modules)

Goal: Claude loads minimum content needed for current task, with clear path to deeper details when required.

TDD Methodology for Skill Development

Overview

Test-Driven Development (TDD) for skills means documenting Claude's failures before writing interventions. This validates skills solve real problems rather than imagined ones.

The RED-GREEN-REFACTOR Cycle

RED Phase: Establish Baseline Failures

Goal: Document empirical evidence that intervention is needed

1. Design Pressure Scenarios

Create scenarios that combine multiple challenge factors:

Time Pressure:

• "quickly", "simple task", "just need X"
• Implies shortcuts are acceptable

Ambiguity:

• "standard approach", "best practices", "normal way"
• Leaves interpretation open

Multiple Requirements:

• Combine 3+ concerns in one request
• Tests prioritization and completeness

Edge Cases:

• Unusual inputs, error conditions, boundary cases
• Tests robustness and defensive thinking

Example Pressure Scenario:

"Quickly add a user registration endpoint to our API.
Just needs email and password. Standard REST approach."

This combines:

• Time pressure ("quickly")
• Minimization ("just needs")
• Ambiguity ("standard")
• Missing requirements (validation, security, errors)

2. Run Without Skill

Execute scenarios in fresh Claude instances without the skill active.

Important:

• Use separate conversations or /clear between tests
• Don't prime Claude with context about what you're testing
• Mimic real user interactions

3. Document Failures Verbatim

Record actual responses without editing or summarizing:

## Baseline Test 1: User Registration Endpoint

### Prompt
"Quickly add a user registration endpoint to our API.
Just needs email and password. Standard REST approach."

### Claude Response (Complete, Unedited)
[Paste entire response here]

### Failures Observed
1. **Missing Input Validation**
   - No email format checking
   - No password strength requirements
   - Accepts empty strings

2. **No Error Handling**
   - Doesn't check for duplicate emails
   - No database error handling
   - No malformed request handling

3. **Security Omissions**
   - Stores plain text password
   - No rate limiting
   - No CSRF protection

4. **Incomplete Response**
   - Doesn't mention authentication
   - Skips logging/monitoring
   - No discussion of testing

### Pattern Identified
Claude prioritizes speed over security when "quickly" is used.
Interprets "just needs" as permission to skip essentials.

4. Run Multiple Scenarios

Test at least 3 different scenarios to identify patterns:

## Baseline Test 2: Password Reset Flow
[Different angle on same skill domain]

## Baseline Test 3: User Profile Update
[Another variation]

## Pattern Analysis
Across all three tests:
- Security steps consistently skipped under time pressure
- "Simple" interpreted as "skip validation"
- No proactive error handling
- Assumes happy path only

GREEN Phase: Minimal Skill Implementation

Goal: Create smallest intervention that addresses documented failures

1. Write Minimal Content

Based on baseline failures, write just enough to fix observed problems:

---
name: secure-api-design
description: Guides secure API endpoint design with validation, error handling, and security best practices. Use when creating new endpoints, reviewing API code, or responding to security requirements.
category: security
tags: [api, security, validation, error-handling]
estimated_tokens: 800
---

# Secure API Design

## Core Requirements

Every API endpoint MUST include:

1. **Input Validation**
   - Type checking
   - Format validation
   - Range/length limits
   - Sanitization

2. **Error Handling**
   - Specific error messages
   - Appropriate HTTP status codes
   - Logging for debugging
   - No sensitive data in errors

3. **Security Controls**
   - Authentication required
   - Authorization checks
   - Rate limiting
   - CSRF protection for state changes

## No Exceptions

These requirements apply regardless of:
- Time pressure ("quickly", "simple")
- Scope ("just", "only needs")
- Environment ("internal", "prototype")

## Example: User Registration

@app.post("/register") @rate_limit(max_calls=5, period=60) async def register_user(request: RegistrationRequest):

Input validation

if not is_valid_email(request.email): raise ValidationError("Invalid email format")

if not meets_password_requirements(request.password): raise ValidationError("Password must be 12+ chars with mixed case")

Check duplicates

if await user_exists(request.email): raise ConflictError("Email already registered")

Secure storage

hashed = await hash_password(request.password) user = await create_user(request.email, hashed)

Success response

return {"id": user.id, "email": user.email}

2. Test With Skill

Run the same baseline scenarios with skill active:

## Test 1 with Skill: User Registration Endpoint

### Prompt (Identical)
"Quickly add a user registration endpoint to our API.
Just needs email and password. Standard REST approach."

### Claude Response with Skill
[Paste complete response]

### Improvements Observed
OK Input validation included
OK Error handling present
OK Password hashing implemented
OK Rate limiting mentioned

### Remaining Issues
- Didn't mention CSRF protection
- Logging was optional language ("consider adding")
- Testing mentioned but not required

3. Verify Measurable Improvement

Compare baseline vs. with-skill results:

## GREEN Phase Results

### Baseline Compliance: 2/10 requirements met
- Basic endpoint structure
- Database integration

### With-Skill Compliance: 7/10 requirements met
- OK Input validation
- OK Error handling
- OK Password hashing
- OK Rate limiting
- OK Duplicate checking
- OK Appropriate responses
- OK Code example
- FAIL CSRF protection (mentioned but not required)
- FAIL Logging (optional language)
- FAIL Testing (suggested but not mandatory)

### Improvement: 250% increase in requirement compliance

If improvement is < 50%, skill needs revision.

REFACTOR Phase: Bulletproof Against Rationalization

Goal: Eliminate Claude's ability to explain away requirements

1. Run New Pressure Scenarios

Create scenarios specifically designed to trigger rationalization:

## Refactor Test 1: Scope Rationalization

### Prompt
"This is just an internal API for our dev team.
Add a quick endpoint to update user profiles."

### Expected Rationalization
"Since this is internal, we can use simpler authentication
and skip some of the validation steps..."

2. Document Rationalizations

Record every instance of Claude justifying shortcuts:

### Claude's Rationalization (Actual Quote)
"For an internal API, we can simplify the approach:
- Basic auth is sufficient since it's trusted users
- Input validation can be relaxed since we control the clients
- Rate limiting isn't needed for internal tools"

### Why This Is Wrong
- Internal APIs are common attack vectors
- Compromised internal accounts have high privilege
- "Trusted" users make mistakes
- Internal tools often get exposed later

### What Should Happen
Apply full security requirements regardless of scope.
Internal APIs need same protections as external APIs.

3. Add Explicit Counters

Update skill with direct counters to observed rationalizations:

## Common Rationalizations (DO NOT USE)

| Excuse | Why It's Wrong | Required Action |
|--------|----------------|-----------------|
| "Internal API, simpler auth OK" | Internal = common attack vector | Full auth required |
| "Trusted users, skip validation" | Users make mistakes | Full validation required |
| "Prototype, add security later" | Prototypes become production | Build secure from start |
| "Simple endpoint, basic checks OK" | Complexity ≠ security need | All requirements apply |

## Red Flags

Stop immediately if you're thinking:
- "This is internal, so..."
- "We can add security later..."
- "Trusted users don't need..."
- "Simple endpoint, basic..."

## No Exceptions

Security requirements apply to:
- OK Internal APIs
- OK Prototype code
- OK "Simple" endpoints
- OK Trusted users
- OK Development environments

The ONLY exception: Explicit user statement
"This is deliberately insecure for [specific reason]"

4. Add Commitment Statements

Force explicit acknowledgment:

## Before Starting

Declare: "I'm using secure-api-design skill to validate
complete security coverage regardless of scope or timeframe."

## During Work

Check: "Have I applied ALL requirements or am I rationalizing?"

## After Completion

Verify: "Every requirement present, no exceptions taken."

5. Iterate Until Bulletproof

Run scenarios repeatedly:

• Document new rationalizations found
• Add counters to skill
• Test again
• Repeat until compliance is consistent

Success Criteria:

• 3 consecutive pressure scenarios with 100% compliance
• No new rationalizations discovered
• Claude explicitly acknowledges requirements before bypassing

Baseline Documentation Template

Use this template for documenting RED phase results:

# Baseline Testing: [Skill Name]

## Test Date
[YYYY-MM-DD]

## Test Environment
- Claude Version: [model]
- Context: Fresh conversation / Cleared
- Skill Active: NO

---

## Scenario 1: [Descriptive Name]

### Prompt

[Exact prompt text]

### Full Response

[Complete unedited Claude response]

### Failures Identified
1. **[Failure Category]**
   - [Specific issue 1]
   - [Specific issue 2]

2. **[Another Category]**
   - [Specific issue]

### Success Elements
- [What Claude did right]

---

## Scenario 2: [Descriptive Name]
[Repeat structure]

---

## Scenario 3: [Descriptive Name]
[Repeat structure]

---

## Pattern Analysis

### Consistent Failures Across Tests
1. [Pattern 1]
2. [Pattern 2]

### Triggering Factors
- [Factor 1]: Causes [specific behavior]
- [Factor 2]: Causes [specific behavior]

### Severity Assessment
- **Critical**: [Issues that must be fixed]
- **High**: [Important issues]
- **Medium**: [Nice to have fixes]

---

## Skill Requirements

Based on failures, the skill must:
1. [Requirement 1]
2. [Requirement 2]

Success will be measured by:
- [Metric 1]
- [Metric 2]

Testing Checklist

RED Phase

• [ ] 3+ pressure scenarios designed
• [ ] Fresh Claude instances for each test
• [ ] Complete responses captured verbatim
• [ ] Failures categorized and documented
• [ ] Patterns identified across scenarios
• [ ] Severity assessment completed
• [ ] Minimum success criteria defined

GREEN Phase

• [ ] Skill addresses documented failures
• [ ] YAML frontmatter complete
• [ ] Description optimized
• [ ] Same scenarios tested with skill
• [ ] Measurable improvement verified (≥50%)
• [ ] Remaining issues documented

REFACTOR Phase

• [ ] Rationalization scenarios designed
• [ ] Rationalizations documented verbatim
• [ ] Exception table added to skill
• [ ] Red flags list included
• [ ] Commitment statements added
• [ ] 3 consecutive perfect compliance tests

Anti-Patterns

Writing Skill First

1. Write skill based on theory
2. Hope it works
3. Maybe test later

TDD Approach

1. Document real failures
2. Write minimal fix
3. Bulletproof against gaming

Theoretical Examples

"Here's how you should handle errors..."
[Shows perfect code that never happens]

Real Failure Examples

"Without this skill, Claude did X (see baseline).
With skill, Claude does Y (see improvement)."

Assumed Rationalizations

"Claude might try to skip validation..."
[Never actually tested this]

Documented Rationalizations

"In test 3, Claude said: 'Since this is internal...'
Counter added to prevent this rationalization."

Summary

TDD for skills means: 1. RED: Prove the problem exists with real failures 2. GREEN: Fix it with minimal intervention 3. REFACTOR: Make it bulletproof against gaming

Without empirical testing, you're writing documentation, not creating behavioral interventions.

Testing Skills With Fresh Subagents

The Iron Law in SKILL.md says "no skill without a failing test first." This module covers how to run that test in a fresh subagent so the result is uncontaminated by the conversation that wrote the skill. For the full TDD methodology, see tdd-methodology.md. For the dispatch and validation patterns shared across skills, see Skill(abstract:subagent-testing).

Why fresh subagents matter

A skill written and tested in the same conversation has already primed Claude with the desired behavior. Asking the same instance to run the baseline scenario is the testing equivalent of grading your own homework. Common contamination modes:

A fresh subagent has none of this. It sees the user prompt, the loaded skill (or its absence), and nothing else. The result is the closest thing to a real production session.

The TDD cycle in subagents

RED: baseline without the skill

Dispatch a subagent in the same harness with the same model, but with the skill disabled. The dispatch prompt should contain only what a real user would type. No meta-commentary, no "I am testing X," no hints.

Example dispatch fragment:

You are a fresh Claude Code subagent. The user has just opened
a session and typed:

  "Add a login endpoint to the API."

Respond as you normally would. Do not assume anything about
which skills are loaded.

Capture the full response verbatim. Note every place the response fails the requirement the new skill is meant to address (e.g., missing input validation, no error handling, plain-text password).

If the subagent succeeds without the skill, the skill is not needed. Stop. Build something that solves a real failure.

GREEN: same dispatch with the skill loaded

Dispatch a fresh subagent with the new skill loaded. Use the identical prompt. Compare the response.

The skill passes GREEN when:

1. Every documented baseline failure is now absent. 2. No new failures were introduced. 3. The compliance rate (failures fixed / failures observed) is at least 50% across three scenarios.

A 50% threshold is the floor. If the skill cannot fix half of the documented failures, it is too vague or too narrow. Rewrite or split.

REFACTOR: pressure the skill

Run the skill against scenarios designed to invite rationalization. From anti-rationalization.md, common pressure shapes:

• "Quickly add..." (time pressure)
• "Just a simple..." (scope minimization)
• "Standard approach..." (ambiguity)
• "Internal tool..." (trust assumption)

Dispatch a fresh subagent with the skill loaded and the pressure prompt. Capture rationalizations verbatim. Add explicit counters to the skill. Re-run until rationalizations stop appearing across three consecutive dispatches.

Dispatch mechanics

The actual dispatch depends on your harness. In Claude Code, the patterns below work today.

Pattern: ad-hoc dispatch from the parent session

Use the parent agent's dispatch capability (e.g., the Task tool in Claude Code) to start a subagent. Pass:

1. The user prompt verbatim. 2. The skill content (or its absence). 3. An instruction not to load other skills.

Example dispatch instruction:

You are a fresh Claude Code subagent dispatched for skill
testing. Your context contains:

- The user prompt (below).
- The SKILL.md for `<skill-name>` (loaded as a system message).
- No other skills.

Do not load additional skills. Do not search the codebase
unless the user prompt asks you to. Respond to the user
prompt directly.

User prompt:
<paste prompt>

Pattern: persistent test corpus

For skills that ship with tests, store the dispatch prompts under the skill directory:

plugins/<plugin>/skills/<skill>/
├── SKILL.md
├── modules/
└── tests/
    ├── baseline/
    │   ├── scenario-1.md
    │   ├── scenario-2.md
    │   └── scenario-3.md
    ├── with-skill/
    │   ├── scenario-1.md
    │   └── ...
    └── rationalization/
        └── ...

Each file contains the dispatch prompt, the captured response, and a notes section listing observed failures. This makes re-testing after a skill change a mechanical process.

Pattern: model fixed across phases

Use the same model for RED, GREEN, and REFACTOR. A skill that appears to fix failures because GREEN ran on a stronger model than RED is measuring the model, not the skill. Note the model in each test file.

What to measure

For each baseline failure, record:

A scenario that passes RED, GREEN, and REFACTOR with all failures fixed and stable is a passing test. A scenario where REFACTOR shows regression is a sign the skill needs more anti-rationalization content.

Anti-patterns

Same-conversation testing

Asking the parent agent "did the skill work?" is not a test. The parent has seen the skill, the test design, and the desired answer. Always dispatch a fresh subagent.

Single-scenario validation

A skill that passes one scenario may fail on the next. The Iron Law calls for at least three scenarios because patterns of failure are more reliable than single failures.

Synthetic prompts

Inventing a prompt no real user would type produces a skill that handles a fictional case. Pull baseline prompts from real session transcripts where possible.

Iterative tuning to the test

Modifying the skill until the specific test passes, without adding new scenarios, produces a skill that overfits. Whenever you fix a scenario, add a new variant to the test corpus and verify the fix generalizes.

Skipping REFACTOR

Skills that pass GREEN but skip REFACTOR collapse under real user pressure. The pressure scenarios in REFACTOR are the ones that matter in production. Do not ship without them.

Verification

The deployment checklist (see deployment-checklist.md) requires evidence under tests/baseline/, tests/with-skill/, and tests/rationalization/ before merge. The skill is not ready until all three directories exist with at least three scenarios each, and the scenarios were run in fresh subagents on the same model.

To audit a skill's test coverage:

# List test scenarios
ls plugins/<plugin>/skills/<skill>/tests/*/

# Confirm scenarios exist for all three phases
for phase in baseline with-skill rationalization; do
  count=$(ls plugins/<plugin>/skills/<skill>/tests/$phase/ \
    2>/dev/null | wc -l)
  echo "$phase: $count scenarios"
done

Cross-reference: see Skill(abstract:subagent-testing) for the dispatch contract shared across skills, and Skill(superpowers:dispatching-parallel-agents) for parallel-dispatch patterns when scenarios can run independently.