• Technique wasn't intuitively obvious to you
• You'd reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in CLAUDE.md)
• Mechanical constraints (if it's enforceable with regex/validation, automate it - save documentation for judgment calls)

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

1. Heavy reference (100+ lines) - API docs, comprehensive syntax
2. Reusable tools - Scripts, utilities, templates

• Principles and concepts
• Code patterns (< 50 lines)
• Everything else

• Only two fields supported:

  name

  and

  description

• Max 1024 characters total

• name

  : Use letters, numbers, and hyphens only (no parentheses, special chars)

• description

  : Third-person, describes ONLY when to use (NOT what it does)
  • Start with "Use when..." to focus on triggering conditions
  • Include specific symptoms, situations, and contexts
  • NEVER summarize the skill's process or workflow (see CSO section for why)
  • Keep under 500 characters if possible

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

• Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
• Symptoms: "flaky", "hanging", "zombie", "pollution"
• Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
• Tools: Actual commands, library names, file types

• V

  creating-skills

  not

  skill-creation

• V

  condition-based-waiting

  not

  async-test-helpers

• getting-started workflows: <150 words each
• Frequently-loaded skills: <200 words total
• Other skills: <500 words (still be concise)

undefined

• V Good:

  **REQUIRED SUB-SKILL:** Use tdd

• V Good:

  **REQUIRED BACKGROUND:** You MUST understand debugging

• X Bad:

  See skills/testing/test-driven-development

  (unclear if required)
• X Bad:

  @skills/testing/test-driven-development/SKILL.md

  (force-loads, burns context)

@

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

• Non-obvious decision points
• Process loops where you might stop too early
• "When to use A vs B" decisions

• Reference material -> Tables, lists
• Code examples -> Markdown blocks
• Linear instructions -> Numbered lists
• Labels without semantic meaning (step1, helper2)

render-graphs.js

./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

• Testing techniques -> TypeScript/JavaScript
• System debugging -> Shell/Python
• Data processing -> Python

• Complete and runnable
• Well-commented explaining WHY
• From real scenario
• Shows pattern clearly
• Ready to adapt (not generic template)

• Implement in 5+ languages
• Create fill-in-the-blank templates
• Write contrived examples

NO SKILL WITHOUT A FAILING TEST FIRST

• Not for "simple additions"
• Not for "just adding a section"
• Not for "documentation updates"
• Don't keep untested changes as "reference"
• Don't "adapt" while running tests
• Delete means delete

• Academic questions: Do they understand the rules?
• Pressure scenarios: Do they comply under stress?
• Multiple pressures combined: time + sunk cost + exhaustion
• Identify rationalizations and add explicit counters

• Application scenarios: Can they apply the technique correctly?
• Variation scenarios: Do they handle edge cases?
• Missing information tests: Do instructions have gaps?

• Recognition scenarios: Do they recognize when pattern applies?
• Application scenarios: Can they use the mental model?
• Counter-examples: Do they know when NOT to apply?

• Retrieval scenarios: Can they find the right information?
• Application scenarios: Can they use what they found correctly?
• Gap testing: Are common use cases covered?

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

</Good>

• Code before test
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "This is different because..."

undefined

• What choices did they make?
• What rationalizations did they use (verbatim)?
• Which pressures triggered violations?

• How to write pressure scenarios
• Pressure types (time, sunk cost, authority, exhaustion)
• Plugging holes systematically
• Meta-testing techniques

• Create multiple skills in batch without testing each
• Move to next skill before current one is verified
• Skip testing because "batching is more efficient"

• Create pressure scenarios (3+ combined pressures for discipline skills)
• Run scenarios WITHOUT skill - document baseline behavior verbatim
• Identify patterns in rationalizations/failures

• Name uses only letters, numbers, hyphens (no parentheses/special chars)
• YAML frontmatter with only name and description (max 1024 chars)
• Description starts with "Use when..." and includes specific triggers/symptoms
• Description written in third person
• Keywords throughout for search (errors, symptoms, tools)
• Clear overview with core principle
• Address specific baseline failures identified in RED
• Code inline OR link to separate file
• One excellent example (not multi-language)
• Run scenarios WITH skill - verify agents now comply

• Identify NEW rationalizations from testing
• Add explicit counters (if discipline skill)
• Build rationalization table from all test iterations
• Create red flags list
• Re-test until bulletproof

• Small flowchart only if decision non-obvious
• Quick reference table
• Common mistakes section
• No narrative storytelling
• Supporting files only for tools or heavy reference

• Commit skill to git and push to your fork (if configured)
• Consider contributing back via PR (if broadly useful)

1. Encounters problem ("tests are flaky")
2. Finds SKILL (description matches)
3. Scans overview (is this relevant?)
4. Reads patterns (quick reference table)
5. Loads example (only when implementing)

• Write like humans speak. Avoid corporate jargon and marketing fluff.
• Be confident and direct. Avoid softening phrases like "I think," "maybe," or "could."
• Use active voice instead of passive voice.
• Use positive phrasing - say what something IS rather than what it isn't.
• Say "you" more than "we" when addressing external audiences.
• Use contractions like "I'll," "won't," and "can't" for a warmer tone.

• Be specific with facts and data instead of vague superlatives.
• Back up claims with concrete examples or metrics.
• Highlight customers and community members over company achievements.
• Use realistic, product-based examples instead of

  foo/bar/baz

  in code.
• Make content concrete, visual, and falsifiable.

• Make a promise in the title so readers know exactly what they'll get if they click.
• Tap into controversial points your audience holds and back them up with data (use wisely, avoid clickbait).
• Share something uniquely helpful that makes readers better at meaningful aspects of their lives.
• Avoid vague titles like "My Thoughts On XYZ." Titles should be opinions or shareable facts.
• Write placeholder titles first, complete the content, then spend time iterating on titles at the end.

• a bit

  -> remove

• a little

  -> remove

• actually/actual

  -> remove

• agile

  -> remove

• arguably

  -> remove

• assistance

  -> "help"

• attempt

  -> "try"

• battle tested

  -> remove

• best practices

  -> "proven approaches"

• blazing fast/lightning fast

  -> "build XX% faster"

• business logic

  -> remove

• cognitive load

  -> remove

• commence

  -> "start"

• delve

  -> "go into"

• disrupt/disruptive

  -> remove

• facilitate

  -> "help" or "ease"

• game-changing

  -> specific benefit

• great

  -> remove or be specific

• implement

  -> "do"

• individual

  -> "man" or "woman"

• initial

  -> "first"

• innovative

  -> remove

• just

  -> remove

• leverage

  -> "use"

• mission-critical

  -> "important"

• modern/modernized

  -> remove

• numerous

  -> "many"

• out of the box

  -> remove

• performant

  -> "fast and reliable"

• pretty/quite/rather/really/very

  -> remove

• referred to as

  -> "called"

• remainder

  -> "rest"

• robust

  -> "strong"

• seamless/seamlessly

  -> "automatic"

• sufficient

  -> "enough"

• that

  -> often removable, context dependent

• thing

  -> be specific

• utilize

  -> "use"

• webinar

  -> "online event"

• I think/I believe/we believe

  -> state directly

• it seems

  -> remove

• sort of/kind of

  -> remove

• pretty much

  -> remove

• a lot/a little

  -> be specific

• By developers, for developers

  -> remove

• We can't wait to see what you'll build

  -> remove

• We obsess over ___

  -> remove

• The future of ___

  -> remove

• We're excited

  -> "We look forward"

• Today, we're excited to

  -> remove

• Replace em dashes (—) with semicolons, commas, or sentence breaks.
• Avoid starting responses with "Great question!", "You're right!", or "Let me help you."
• Don't use phrases like "Let's dive into..."
• Skip cliché intros like "In today's fast-paced digital world" or "In the ever-evolving landscape of."
• Avoid phrases like "it's not just [x], it's [y]."
• Avoid self-referential disclaimers like "As an AI" or "I'm here to help you with."
• Don't use high-school essay closers: "In conclusion," "Overall," or "To summarize."
• Avoid numbered lists in cases where bullets work better.
• Don't end with "Hope this helps!" or similar closers.
• Avoid overusing transition words like "Furthermore," "Additionally," or "Moreover."
• Replace "In conclusion" with direct statements.
• Avoid hedge words: "might," "perhaps," "potentially" unless uncertainty is real.
• Don't stack hedging phrases: "may potentially," "it's important to note that."
• Don't create perfectly symmetrical paragraphs or lists that start with "Firstly... Secondly..."
• Avoid title-case headings; prefer sentence casing.
• Remove Unicode artifacts when copy-pasting: smart quotes ("), em-dashes, non-breaking spaces.
• Use `` instead of ''.
• Delete empty citation placeholders like "[1]" with no actual source.

• Use Oxford commas consistently.
• Use exclamation points sparingly.
• Sentences can start with "But" and "And" - but don't overuse.
• Use periods instead of commas when possible for clarity.

.claude/context/memory/learnings.md

• New pattern ->

  .claude/context/memory/learnings.md

• Issue found ->

  .claude/context/memory/issues.md

• Decision made ->

  .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.