'v1'

extensions/awesome-skills-plugin/skills/writing-skills/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: writing-skills
+description: "Use when creating, updating, or improving agent skills."
+category: meta
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Writing Skills (Excellence)
+
+Dispatcher for skill creation excellence. Use the decision tree below to find the right template and standards.
+
+## ⚡ Quick Decision Tree
+
+### What do you need to do?
+
+1. **Create a NEW skill:**
+   - Is it simple (single file, <200 lines)? → [Tier 1 Architecture](references/tier-1-simple/README.md)
+   - Is it complex (multi-concept, 200-1000 lines)? → [Tier 2 Architecture](references/tier-2-expanded/README.md)
+   - Is it a massive platform (10+ products, AWS, Convex)? → [Tier 3 Architecture](references/tier-3-platform/README.md)
+
+2. **Improve an EXISTING skill:**
+   - Fix "it's too long" -> [Modularize (Tier 3)](references/templates/tier-3-platform.md)
+   - Fix "AI ignores rules" -> [Anti-Rationalization](references/anti-rationalization/README.md)
+   - Fix "users can't find it" -> [CSO (Search Optimization)](references/cso/README.md)
+
+3. **Verify Compliance:**
+   - Check metadata/naming -> [Standards](references/standards/README.md)
+   - Add tests -> [Testing Guide](references/testing/README.md)
+
+## 📚 Component Index
+
+| Component | Purpose |
+|-----------|---------|
+| **[CSO](references/cso/README.md)** | "SEO for LLMs". How to write descriptions that trigger. |
+| **[Standards](references/standards/README.md)** | File naming, YAML frontmatter, directory structure. |
+| **[Anti-Rationalization](references/anti-rationalization/README.md)**| How to write rules that agents won't ignore. |
+| **[Testing](references/testing/README.md)** | How to ensure your skill actually works. |
+
+## 🛠️ Templates
+
+- [Technique Skill](references/templates/technique.md) (How-to)
+- [Reference Skill](references/templates/reference.md) (Docs)
+- [Discipline Skill](references/templates/discipline.md) (Rules)
+- [Pattern Skill](references/templates/pattern.md) (Design Patterns)
+
+## When to Use
+- Creating a NEW skill from scratch
+- Improving an EXISTING skill that agents ignore
+- Debugging why a skill isn't being triggered
+- Standardizing skills across a team
+
+## How It Works
+
+1. **Identify goal** → Use decision tree above
+2. **Select template** → From `references/templates/`
+3. **Apply CSO** → Optimize description for discovery
+4. **Add anti-rationalization** → For discipline skills
+5. **Test** → RED-GREEN-REFACTOR cycle
+
+## Quick Example
+
+```yaml
+---
+name: my-technique
+description: Use when [specific symptom occurs].
+metadata:
+  category: technique
+  triggers: error-text, symptom, tool-name
+---
+
+# My Technique
+
+## When to Use
+- [Symptom A]
+- [Error message]
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Description summarizes workflow | Use "Use when..." triggers only |
+| No `metadata.triggers` | Add 3+ keywords |
+| Generic name ("helper") | Use gerund (`creating-skills`) |
+| Long monolithic SKILL.md | Split into `references/` |
+
+See [gotchas.md](gotchas.md) for more.
+
+## ✅ Pre-Deploy Checklist
+
+Before deploying any skill:
+
+- [ ] `name` field matches directory name exactly
+- [ ] `SKILL.md` filename is ALL CAPS
+- [ ] Description starts with "Use when..."
+- [ ] `metadata.triggers` has 3+ keywords
+- [ ] Total lines < 500 (use `references/` for more)
+- [ ] No `@` force-loading in cross-references
+- [ ] Tested with real scenarios
+
+## 🔗 Related Skills
+
+- **opencode-expert**: For OpenCode environment configuration
+- Use `/write-skill` command for guided skill creation
+
+## Examples
+
+**Create a Tier 1 skill:**
+```bash
+mkdir -p ~/.config/opencode/skills/my-technique
+touch ~/.config/opencode/skills/my-technique/SKILL.md
+```
+
+**Create a Tier 2 skill:**
+```bash
+mkdir -p ~/.config/opencode/skills/my-skill/references/core
+touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}
+touch ~/.config/opencode/skills/my-skill/references/core/README.md
+```
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

extensions/awesome-skills-plugin/skills/writing-skills/examples.md

@@ -0,0 +1,282 @@
+# Skill Templates & Examples
+
+Complete, copy-paste templates for each skill type.
+
+---
+
+## Template: Technique Skill
+
+For how-to guides that teach a specific method.
+
+```markdown
+---
+name: technique-name
+description: >-
+  Use when [specific symptom].
+metadata:
+  category: technique
+  triggers: error-text, symptom, tool-name
+---
+
+# Technique Name
+
+## Overview
+
+[1-2 sentence core principle]
+
+## When to Use
+
+- [Symptom A]
+- [Symptom B]
+- [Error message text]
+
+**NOT for:**
+- [When to avoid]
+
+## The Problem
+
+```javascript
+// Bad example
+function badCode() {
+  // problematic pattern
+}
+```
+
+## The Solution
+
+```javascript
+// Good example
+function goodCode() {
+  // improved pattern
+}
+```
+
+## Step-by-Step
+
+1. [First step]
+2. [Second step]
+3. [Final step]
+
+## Quick Reference
+
+| Scenario | Approach |
+|----------|----------|
+| Case A | Solution A |
+| Case B | Solution B |
+
+## Common Mistakes
+
+**Mistake 1:** [Description]
+- Wrong: `bad code`
+- Right: `good code`
+```
+
+---
+
+## Template: Reference Skill
+
+For documentation, APIs, and lookup tables.
+
+```markdown
+---
+name: reference-name
+description: >-
+  Use when working with [domain].
+metadata:
+  category: reference
+  triggers: tool, api, specific-terms
+---
+
+# Reference Name
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `cmd1` | Does X |
+| `cmd2` | Does Y |
+
+## Common Patterns
+
+**Pattern A:**
+```bash
+example command
+```
+
+**Pattern B:**
+```bash
+another example
+```
+
+## Detailed Docs
+
+For more options, run `--help` or see:
+- patterns.md
+- [examples.md](examples.md)
+```
+
+---
+
+## Template: Discipline Skill
+
+For rules that agents must follow. Requires anti-rationalization techniques.
+
+```markdown
+---
+name: discipline-name
+description: >-
+  Use when [BEFORE violation].
+metadata:
+  category: discipline
+  triggers: new feature, code change, implementation
+---
+
+# Rule Name
+
+## Iron Law
+
+**[SINGLE SENTENCE ABSOLUTE RULE]**
+
+Violating the letter IS violating the spirit.
+
+## The Rule
+
+1. ALWAYS [step 1]
+2. NEVER [step 2]
+3. [Step 3]
+
+## Violations
+
+[Action before rule]? **Delete it. Start over.**
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it
+- Delete means delete
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple" | Simple code breaks. Rule takes 30 seconds. |
+| "I'll do it after" | After = never. Do it now. |
+| "Spirit not ritual" | The ritual IS the spirit. |
+
+## Red Flags - STOP
+
+- [Flag 1]
+- [Flag 2]
+- "This is different because..."
+
+**All mean:** Delete. Start over.
+
+## Valid Exceptions
+
+- [Exception 1]
+- [Exception 2]
+
+**Everything else:** Follow the rule.
+```
+
+---
+
+## Template: Pattern Skill
+
+For mental models and design patterns.
+
+```markdown
+---
+name: pattern-name
+description: >-
+  Use when [recognizable symptom].
+metadata:
+  category: pattern
+  triggers: complexity, hard-to-follow, nested
+---
+
+# Pattern Name
+
+## The Pattern
+
+[1-2 sentence core idea]
+
+## Recognition Signs
+
+- [Sign that pattern applies]
+- [Another sign]
+- [Code smell]
+
+## Before
+
+```typescript
+// Complex/problematic
+function before() {
+  // nested, confusing
+}
+```
+
+## After
+
+```typescript
+// Clean/improved
+function after() {
+  // flat, clear
+}
+```
+
+## When NOT to Use
+
+- [Over-engineering case]
+- [Simple case that doesn't need it]
+
+## Impact
+
+**Before:** [Problem metric]
+**After:** [Improved metric]
+```
+
+---
+
+## Real Example: Condition-Based Waiting
+
+```yaml
+---
+name: condition-based-waiting
+description: >-
+  Use when tests have race conditions or timing dependencies.
+metadata:
+  category: technique
+  triggers: flaky tests, timeout, race condition, sleep, setTimeout
+---
+```
+
+```markdown
+# Condition-Based Waiting
+
+## Overview
+
+Replace `sleep(ms)` with `waitFor(() => condition)`.
+
+## When to Use
+
+- Tests pass sometimes, fail other times
+- Tests use `sleep()` or `setTimeout()`
+- "Works on my machine"
+
+## The Fix
+
+```typescript
+// ❌ Bad
+await sleep(2000);
+expect(element).toBeVisible();
+
+// ✅ Good
+await waitFor(() => element.isVisible(), { timeout: 5000 });
+expect(element).toBeVisible();
+```
+
+## Impact
+
+- Flaky tests: 15/100 → 0/100
+- Speed: 40% faster (no over-waiting)
+```

extensions/awesome-skills-plugin/skills/writing-skills/gotchas.md

@@ -0,0 +1,197 @@
+---
+description: Common pitfalls and tribal knowledge for skill creation.
+metadata:
+  tags: [gotchas, troubleshooting, mistakes]
+---
+
+# Skill Writing Gotchas
+
+Tribal knowledge to avoid common mistakes.
+
+## YAML Frontmatter
+
+### Invalid Syntax
+
+```yaml
+# ❌ BAD: Mixed list and map
+metadata:
+  references: 
+  triggers: a, b, c
+  - item1
+  - item2
+
+# ✅ GOOD: Consistent structure
+metadata:
+  triggers: a, b, c
+  references:
+    - item1
+    - item2
+```
+
+### Multiline Description
+
+```yaml
+# ❌ BAD: Line breaks create parsing errors
+description: Use when creating skills.
+  Also for updating.
+
+# ✅ GOOD: Use YAML multiline syntax
+description: >-
+  Use when creating or updating skills.
+  Triggers: new skill, update skill
+```
+
+## Naming
+
+### Directory Must Match `name` Field
+
+```
+# ❌ BAD
+directory: my-skill/
+name: mySkill  # Mismatch!
+
+# ✅ GOOD
+directory: my-skill/
+name: my-skill  # Exact match
+```
+
+### SKILL.md Must Be ALL CAPS
+
+```
+# ❌ BAD
+skill.md
+Skill.md
+
+# ✅ GOOD
+SKILL.md
+```
+
+## Discovery
+
+### Description = Triggers, NOT Workflow
+
+```yaml
+# ❌ BAD: Agent reads this and skips the full skill
+description: Analyzes code, finds bugs, suggests fixes
+
+# ✅ GOOD: Agent reads full skill to understand workflow
+description: Use when debugging errors or reviewing code quality
+```
+
+### Pre-Violation Triggers for Discipline Skills
+
+```yaml
+# ❌ BAD: Triggers AFTER violation
+description: Use when you forgot to write tests
+
+# ✅ GOOD: Triggers BEFORE violation
+description: Use when implementing any feature, before writing code
+```
+
+## Token Efficiency
+
+### Skill Loaded Every Conversation = Token Drain
+
+- Frequently-loaded skills: <200 words
+- All others: <500 words
+- Move details to `references/` files
+
+### Don't Duplicate CLI Help
+
+```markdown
+# ❌ BAD: 50 lines documenting all flags
+
+# ✅ GOOD: One line
+Run `mytool --help` for all options.
+```
+
+## Anti-Rationalization (Discipline Skills Only)
+
+### Agents Are Smart at Finding Loopholes
+
+```markdown
+# ❌ BAD: Trust agents will "get the spirit"
+Write test before code.
+
+# ✅ GOOD: Close every loophole explicitly
+Write test before code.
+
+**No exceptions:**
+- Don't keep code as "reference"
+- Don't "adapt" existing code
+- Delete means delete
+```
+
+### Build Rationalization Table
+
+Every excuse from baseline testing goes in the table:
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests-after prove nothing immediately. |
+
+## Cross-References
+
+### Keep References One Level Deep
+
+```markdown
+# ❌ BAD: Nested chain (A → B → C)
+See [patterns.md] → which links to [advanced.md] → which links to [deep.md]
+
+# ✅ GOOD: Flat (A → B, A → C)
+See [patterns.md] and [advanced.md]
+```
+
+### Never Force-Load with @
+
+```markdown
+# ❌ BAD: Burns context immediately
+@skills/my-skill/SKILL.md
+
+# ✅ GOOD: Agent loads when needed
+See [my-skill] for details.
+```
+
+## OpenCode Integration
+
+### Correct Skill Directory
+
+```bash
+# ❌ BAD: Old singular path
+~/.config/opencode/skill/my-skill/
+
+# ✅ GOOD: Plural path
+~/.config/opencode/skills/my-skill/
+```
+
+### Skill Cross-Reference Syntax
+
+```markdown
+# ❌ BAD: File path (fragile)
+See /home/user/.config/opencode/skills/my-skill/SKILL.md
+
+# ✅ GOOD: Skill protocol
+See my-skill
+```
+
+## Tier Selection
+
+### Don't Overthink Tier Choice
+
+```markdown
+# ❌ BAD: Starting with Tier 3 "just in case"
+# Result: Wasted effort, empty reference files
+
+# ✅ GOOD: Start with Tier 1, upgrade when needed
+# Can always add references/ later
+```
+
+### Signals You Need to Upgrade
+
+| Signal | Action |
+|--------|--------|
+| SKILL.md > 200 lines | → Tier 2 |
+| 3+ related sub-topics | → Tier 2 |
+| 10+ products/services | → Tier 3 |
+| "I need X" vs "I want Y" | → Tier 3 decision trees |

extensions/awesome-skills-plugin/skills/writing-skills/graphviz-conventions.dot

@@ -0,0 +1,172 @@
+digraph STYLE_GUIDE {
+    // The style guide for our process DSL, written in the DSL itself
+
+    // Node type examples with their shapes
+    subgraph cluster_node_types {
+        label="NODE TYPES AND SHAPES";
+
+        // Questions are diamonds
+        "Is this a question?" [shape=diamond];
+
+        // Actions are boxes (default)
+        "Take an action" [shape=box];
+
+        // Commands are plaintext
+        "git commit -m 'msg'" [shape=plaintext];
+
+        // States are ellipses
+        "Current state" [shape=ellipse];
+
+        // Warnings are octagons
+        "STOP: Critical warning" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+        // Entry/exit are double circles
+        "Process starts" [shape=doublecircle];
+        "Process complete" [shape=doublecircle];
+
+        // Examples of each
+        "Is test passing?" [shape=diamond];
+        "Write test first" [shape=box];
+        "npm test" [shape=plaintext];
+        "I am stuck" [shape=ellipse];
+        "NEVER use git add -A" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+    }
+
+    // Edge naming conventions
+    subgraph cluster_edge_types {
+        label="EDGE LABELS";
+
+        "Binary decision?" [shape=diamond];
+        "Yes path" [shape=box];
+        "No path" [shape=box];
+
+        "Binary decision?" -> "Yes path" [label="yes"];
+        "Binary decision?" -> "No path" [label="no"];
+
+        "Multiple choice?" [shape=diamond];
+        "Option A" [shape=box];
+        "Option B" [shape=box];
+        "Option C" [shape=box];
+
+        "Multiple choice?" -> "Option A" [label="condition A"];
+        "Multiple choice?" -> "Option B" [label="condition B"];
+        "Multiple choice?" -> "Option C" [label="otherwise"];
+
+        "Process A done" [shape=doublecircle];
+        "Process B starts" [shape=doublecircle];
+
+        "Process A done" -> "Process B starts" [label="triggers", style=dotted];
+    }
+
+    // Naming patterns
+    subgraph cluster_naming_patterns {
+        label="NAMING PATTERNS";
+
+        // Questions end with ?
+        "Should I do X?";
+        "Can this be Y?";
+        "Is Z true?";
+        "Have I done W?";
+
+        // Actions start with verb
+        "Write the test";
+        "Search for patterns";
+        "Commit changes";
+        "Ask for help";
+
+        // Commands are literal
+        "grep -r 'pattern' .";
+        "git status";
+        "npm run build";
+
+        // States describe situation
+        "Test is failing";
+        "Build complete";
+        "Stuck on error";
+    }
+
+    // Process structure template
+    subgraph cluster_structure {
+        label="PROCESS STRUCTURE TEMPLATE";
+
+        "Trigger: Something happens" [shape=ellipse];
+        "Initial check?" [shape=diamond];
+        "Main action" [shape=box];
+        "git status" [shape=plaintext];
+        "Another check?" [shape=diamond];
+        "Alternative action" [shape=box];
+        "STOP: Don't do this" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+        "Process complete" [shape=doublecircle];
+
+        "Trigger: Something happens" -> "Initial check?";
+        "Initial check?" -> "Main action" [label="yes"];
+        "Initial check?" -> "Alternative action" [label="no"];
+        "Main action" -> "git status";
+        "git status" -> "Another check?";
+        "Another check?" -> "Process complete" [label="ok"];
+        "Another check?" -> "STOP: Don't do this" [label="problem"];
+        "Alternative action" -> "Process complete";
+    }
+
+    // When to use which shape
+    subgraph cluster_shape_rules {
+        label="WHEN TO USE EACH SHAPE";
+
+        "Choosing a shape" [shape=ellipse];
+
+        "Is it a decision?" [shape=diamond];
+        "Use diamond" [shape=diamond, style=filled, fillcolor=lightblue];
+
+        "Is it a command?" [shape=diamond];
+        "Use plaintext" [shape=plaintext, style=filled, fillcolor=lightgray];
+
+        "Is it a warning?" [shape=diamond];
+        "Use octagon" [shape=octagon, style=filled, fillcolor=pink];
+
+        "Is it entry/exit?" [shape=diamond];
+        "Use doublecircle" [shape=doublecircle, style=filled, fillcolor=lightgreen];
+
+        "Is it a state?" [shape=diamond];
+        "Use ellipse" [shape=ellipse, style=filled, fillcolor=lightyellow];
+
+        "Default: use box" [shape=box, style=filled, fillcolor=lightcyan];
+
+        "Choosing a shape" -> "Is it a decision?";
+        "Is it a decision?" -> "Use diamond" [label="yes"];
+        "Is it a decision?" -> "Is it a command?" [label="no"];
+        "Is it a command?" -> "Use plaintext" [label="yes"];
+        "Is it a command?" -> "Is it a warning?" [label="no"];
+        "Is it a warning?" -> "Use octagon" [label="yes"];
+        "Is it a warning?" -> "Is it entry/exit?" [label="no"];
+        "Is it entry/exit?" -> "Use doublecircle" [label="yes"];
+        "Is it entry/exit?" -> "Is it a state?" [label="no"];
+        "Is it a state?" -> "Use ellipse" [label="yes"];
+        "Is it a state?" -> "Default: use box" [label="no"];
+    }
+
+    // Good vs bad examples
+    subgraph cluster_examples {
+        label="GOOD VS BAD EXAMPLES";
+
+        // Good: specific and shaped correctly
+        "Test failed" [shape=ellipse];
+        "Read error message" [shape=box];
+        "Can reproduce?" [shape=diamond];
+        "git diff HEAD~1" [shape=plaintext];
+        "NEVER ignore errors" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+        "Test failed" -> "Read error message";
+        "Read error message" -> "Can reproduce?";
+        "Can reproduce?" -> "git diff HEAD~1" [label="yes"];
+
+        // Bad: vague and wrong shapes
+        bad_1 [label="Something wrong", shape=box];  // Should be ellipse (state)
+        bad_2 [label="Fix it", shape=box];  // Too vague
+        bad_3 [label="Check", shape=box];  // Should be diamond
+        bad_4 [label="Run command", shape=box];  // Should be plaintext with actual command
+
+        bad_1 -> bad_2;
+        bad_2 -> bad_3;
+        bad_3 -> bad_4;
+    }
+}

extensions/awesome-skills-plugin/skills/writing-skills/persuasion-principles.md

@@ -0,0 +1,187 @@
+# Persuasion Principles for Skill Design
+
+## Overview
+
+LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
+
+**Research foundation:** Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Persuasion techniques more than doubled compliance rates (33% → 72%, p < .001).
+
+## The Seven Principles
+
+### 1. Authority
+**What it is:** Deference to expertise, credentials, or official sources.
+
+**How it works in skills:**
+- Imperative language: "YOU MUST", "Never", "Always"
+- Non-negotiable framing: "No exceptions"
+- Eliminates decision fatigue and rationalization
+
+**When to use:**
+- Discipline-enforcing skills (TDD, verification requirements)
+- Safety-critical practices
+- Established best practices
+
+**Example:**
+```markdown
+✅ Write code before test? Delete it. Start over. No exceptions.
+❌ Consider writing tests first when feasible.
+```
+
+### 2. Commitment
+**What it is:** Consistency with prior actions, statements, or public declarations.
+
+**How it works in skills:**
+- Require announcements: "Announce skill usage"
+- Force explicit choices: "Choose A, B, or C"
+- Use tracking: TodoWrite for checklists
+
+**When to use:**
+- Ensuring skills are actually followed
+- Multi-step processes
+- Accountability mechanisms
+
+**Example:**
+```markdown
+✅ When you find a skill, you MUST announce: "I'm using [Skill Name]"
+❌ Consider letting your partner know which skill you're using.
+```
+
+### 3. Scarcity
+**What it is:** Urgency from time limits or limited availability.
+
+**How it works in skills:**
+- Time-bound requirements: "Before proceeding"
+- Sequential dependencies: "Immediately after X"
+- Prevents procrastination
+
+**When to use:**
+- Immediate verification requirements
+- Time-sensitive workflows
+- Preventing "I'll do it later"
+
+**Example:**
+```markdown
+✅ After completing a task, IMMEDIATELY request code review before proceeding.
+❌ You can review code when convenient.
+```
+
+### 4. Social Proof
+**What it is:** Conformity to what others do or what's considered normal.
+
+**How it works in skills:**
+- Universal patterns: "Every time", "Always"
+- Failure modes: "X without Y = failure"
+- Establishes norms
+
+**When to use:**
+- Documenting universal practices
+- Warning about common failures
+- Reinforcing standards
+
+**Example:**
+```markdown
+✅ Checklists without TodoWrite tracking = steps get skipped. Every time.
+❌ Some people find TodoWrite helpful for checklists.
+```
+
+### 5. Unity
+**What it is:** Shared identity, "we-ness", in-group belonging.
+
+**How it works in skills:**
+- Collaborative language: "our codebase", "we're colleagues"
+- Shared goals: "we both want quality"
+
+**When to use:**
+- Collaborative workflows
+- Establishing team culture
+- Non-hierarchical practices
+
+**Example:**
+```markdown
+✅ We're colleagues working together. I need your honest technical judgment.
+❌ You should probably tell me if I'm wrong.
+```
+
+### 6. Reciprocity
+**What it is:** Obligation to return benefits received.
+
+**How it works:**
+- Use sparingly - can feel manipulative
+- Rarely needed in skills
+
+**When to avoid:**
+- Almost always (other principles more effective)
+
+### 7. Liking
+**What it is:** Preference for cooperating with those we like.
+
+**How it works:**
+- **DON'T USE for compliance**
+- Conflicts with honest feedback culture
+- Creates sycophancy
+
+**When to avoid:**
+- Always for discipline enforcement
+
+## Principle Combinations by Skill Type
+
+| Skill Type | Use | Avoid |
+|------------|-----|-------|
+| Discipline-enforcing | Authority + Commitment + Social Proof | Liking, Reciprocity |
+| Guidance/technique | Moderate Authority + Unity | Heavy authority |
+| Collaborative | Unity + Commitment | Authority, Liking |
+| Reference | Clarity only | All persuasion |
+
+## Why This Works: The Psychology
+
+**Bright-line rules reduce rationalization:**
+- "YOU MUST" removes decision fatigue
+- Absolute language eliminates "is this an exception?" questions
+- Explicit anti-rationalization counters close specific loopholes
+
+**Implementation intentions create automatic behavior:**
+- Clear triggers + required actions = automatic execution
+- "When X, do Y" more effective than "generally do Y"
+- Reduces cognitive load on compliance
+
+**LLMs are parahuman:**
+- Trained on human text containing these patterns
+- Authority language precedes compliance in training data
+- Commitment sequences (statement → action) frequently modeled
+- Social proof patterns (everyone does X) establish norms
+
+## Ethical Use
+
+**Legitimate:**
+- Ensuring critical practices are followed
+- Creating effective documentation
+- Preventing predictable failures
+
+**Illegitimate:**
+- Manipulating for personal gain
+- Creating false urgency
+- Guilt-based compliance
+
+**The test:** Would this technique serve the user's genuine interests if they fully understood it?
+
+## Research Citations
+
+**Cialdini, R. B. (2021).** *Influence: The Psychology of Persuasion (New and Expanded).* Harper Business.
+- Seven principles of persuasion
+- Empirical foundation for influence research
+
+**Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. University of Pennsylvania.
+- Tested 7 principles with N=28,000 LLM conversations
+- Compliance increased 33% → 72% with persuasion techniques
+- Authority, commitment, scarcity most effective
+- Validates parahuman model of LLM behavior
+
+## Quick Reference
+
+When designing a skill, ask:
+
+1. **What type is it?** (Discipline vs. guidance vs. reference)
+2. **What behavior am I trying to change?**
+3. **Which principle(s) apply?** (Usually authority + commitment for discipline)
+4. **Am I combining too many?** (Don't use all seven)
+5. **Is this ethical?** (Serves user's genuine interests?)

extensions/awesome-skills-plugin/skills/writing-skills/references/anti-rationalization/README.md

@@ -0,0 +1,255 @@
+# Anti-Rationalization Guide
+
+Techniques for bulletproofing skills against agent rationalization.
+
+## The Problem
+
+Discipline-enforcing skills (like TDD) face a unique challenge: smart agents under pressure will find loopholes.
+
+**Example**: Skill says "Write test first". Agent under deadline thinks:
+
+- "This is too simple to test"
+- "I'll test after, same result"
+- "It's the spirit that matters, not ritual"
+
+## Psychology Foundation
+
+Understanding WHY persuasion works helps apply it systematically.
+
+**Research basis**: Cialdini (2021), Meincke et al. (2025)
+
+**Core principles**:
+
+- **Authority**: "The TDD community agrees..."
+- **Commitment**: "You already said you follow TDD..."
+- **Scarcity**: "Missing tests now = bugs later"
+- **Social Proof**: "All tested code passing CI proves value"
+- **Unity**: "We're engineers who value quality"
+
+## Technique 1: Close Every Loophole Explicitly
+
+Don't just state the rule - forbid specific workarounds.
+
+### Bad Example
+
+```markdown
+Write code before test? Delete it.
+```
+
+### Good Example
+
+```markdown
+Write code before test? Delete it. Start over.
+
+**No exceptions**:
+
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+```
+
+**Why it works**: Agents try specific workarounds. Counter each explicitly.
+
+## Technique 2: Address "Spirit vs Letter" Arguments
+
+Add foundational principle early:
+
+```markdown
+**Violating the letter of the rules is violating the spirit of the rules.**
+```
+
+**Why it works**: Cuts off entire class of "I'm following the spirit" rationalizations.
+
+## Technique 3: Build Rationalization Table
+
+Capture excuses from baseline testing. Every rationalization goes in table:
+
+```markdown
+| Excuse                           | Reality                                                                 |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| "Too simple to test"             | Simple code breaks. Test takes 30 seconds.                              |
+| "I'll test after"                | Tests passing immediately prove nothing.                                |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "It's about spirit not ritual"   | The letter IS the spirit. TDD's value comes from the specific sequence. |
+```
+
+**Why it works**: Agents read table, recognize their own thinking, see the counter-argument.
+
+## Technique 4: Create Red Flags List
+
+Make it easy for agents to self-check when rationalizing:
+
+```markdown
+## Red Flags - STOP and Start Over
+
+- Code before test
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "This is different because..."
+
+**All of these mean**: Delete code. Start over with TDD.
+```
+
+**Why it works**: Simple checklist, clear action (delete & restart).
+
+## Technique 5: Update Description for Violation Symptoms
+
+Add to description: symptoms of when you're ABOUT to violate:
+
+```yaml
+# ❌ BAD: Only describes what skill does
+description: TDD methodology for writing code
+
+# ✅ GOOD: Includes pre-violation symptoms
+description: Use when implementing any feature or bugfix, before writing implementation code
+metadata:
+  triggers: new feature, bug fix, code change
+```
+
+**Why it works**: Triggers skill BEFORE violation, not after.
+
+## Technique 6: Use Strong Language
+
+Weak language invites rationalization:
+
+```markdown
+# Weak
+
+You should write tests first.
+Generally, test before code.
+It's better to test first.
+
+# Strong
+
+ALWAYS write test first.
+NEVER write code before test.
+Test-first is MANDATORY.
+```
+
+**Why it works**: No ambiguity, no wiggle room.
+
+## Technique 7: Invoke Commitment & Consistency
+
+Reference agent's own standards:
+
+```markdown
+You claimed to follow TDD.
+TDD means test-first.
+Code-first is NOT TDD.
+
+**Either**:
+
+- Follow TDD (test-first), or
+- Admit you're not doing TDD
+
+Don't redefine TDD to fit what you already did.
+```
+
+**Why it works**: Agents resist cognitive dissonance (Festinger, 1957).
+
+## Technique 8: Provide Escape Hatch for Legitimate Cases
+
+If there ARE valid exceptions, state them explicitly:
+
+```markdown
+## When NOT to Use TDD
+
+- Spike solutions (throwaway exploratory code)
+- One-time scripts deleting in 1 hour
+- Generated boilerplate (verified via other means)
+
+**Everything else**: Use TDD. No exceptions.
+```
+
+**Why it works**: Removes "but this is different" argument for non-exception cases.
+
+## Complete Bulletproofing Checklist
+
+For discipline-enforcing skills:
+
+**Loophole Closing**:
+
+- [ ] Forbidden each specific workaround explicitly?
+- [ ] Added "spirit vs letter" principle?
+- [ ] Built rationalization table from baseline tests?
+- [ ] Created red flags list?
+
+**Strength**:
+
+- [ ] Used strong language (ALWAYS/NEVER)?
+- [ ] Invoked commitment & consistency?
+- [ ] Provided explicit escape hatch?
+
+**Discovery**:
+
+- [ ] Description includes pre-violation symptoms?
+- [ ] Keywords target moment BEFORE violation?
+
+**Testing**:
+
+- [ ] Tested with combined pressures?
+- [ ] Agent complied under maximum pressure?
+- [ ] No new rationalizations found?
+
+## Real-World Example: TDD Skill
+
+### Baseline Rationalizations Found
+
+1. "Too simple to test"
+2. "I'll test after"
+3. "Spirit not ritual"
+4. "Already manually tested"
+5. "This is different because..."
+
+### Counters Applied
+
+**Rationalization table**:
+
+```markdown
+| Excuse               | Reality                                                        |
+| -------------------- | -------------------------------------------------------------- |
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds.                     |
+| "I'll test after"    | Tests passing immediately prove nothing.                       |
+| "Spirit not ritual"  | The letter IS the spirit. TDD's value comes from the sequence. |
+| "Manually tested"    | Manual tests don't run automatically. They rot.                |
+```
+
+**Red flags**:
+
+```markdown
+## Red Flags - STOP
+
+- Code before test
+- "I already tested manually"
+- "Spirit not ritual"
+- "This is different..."
+
+All mean: Delete code. Start over.
+```
+
+**Result**: Agent compliance under combined time + sunk cost pressure.
+
+## Common Mistakes
+
+| Mistake                                | Fix                                                            |
+| -------------------------------------- | -------------------------------------------------------------- |
+| Trust agents will "get the spirit"     | Close explicit loopholes. Agents are smart at rationalization. |
+| Use weak language ("should", "better") | Use ALWAYS/NEVER for discipline rules.                         |
+| Skip rationalization table             | Every excuse needs explicit counter.                           |
+| No red flags list                      | Make self-checking easy.                                       |
+| Generic description                    | Add pre-violation symptoms to trigger skill earlier.           |
+
+## Meta-Strategy
+
+**For each new rationalization**:
+
+1. Document it verbatim (from failed test)
+2. Add to rationalization table
+3. Update red flags list
+4. Re-test
+
+**Iterate until**: Agent can't find ANY rationalization that works.
+
+That's bulletproof.

extensions/awesome-skills-plugin/skills/writing-skills/references/cso/README.md

@@ -0,0 +1,268 @@
+# CSO Guide - Claude Search Optimization
+
+Advanced techniques for making skills discoverable by agents.
+
+## The Discovery Problem
+
+You have 100+ skills. Agent receives a task. How does it find the RIGHT skill?
+
+**Answer**: The `description` field.
+
+## Critical Rule: Description = Triggers, NOT Workflow
+
+### The Trap
+
+When description summarizes workflow, agents take a shortcut.
+
+**Real example that failed**:
+
+```yaml
+# Agent did ONE review instead of TWO
+description: Code review between tasks
+
+# Skill body had flowchart showing TWO reviews:
+# 1. Spec compliance
+# 2. Code quality
+```
+
+**Why it failed**: Agent read description, thought "code review between tasks means one review", never read the flowchart.
+
+**Fix**:
+
+```yaml
+# Agent now reads full skill and follows flowchart
+description: Use when executing implementation plans with independent tasks
+```
+
+### The Pattern
+
+```yaml
+# ❌ BAD: Workflow summary
+description: Analyzes git diff, generates commit message in conventional format
+
+# ✅ GOOD: Trigger conditions only
+description: Use when generating commit messages or reviewing staged changes
+```
+
+## Token Efficiency Critical for Skills
+
+**Problem**: Frequently-loaded skills consume tokens in EVERY conversation.
+
+**Target word counts**:
+
+- Frequently-loaded skills: <200 words total
+- Other skills: <500 words
+
+### Techniques
+
+**1. Move details to tool help**:
+
+```bash
+# ❌ BAD: Document all flags in SKILL.md
+search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
+
+# ✅ GOOD: Reference --help
+search-conversations supports multiple modes. Run --help for details.
+```
+
+**2. Use cross-references**:
+
+```markdown
+# ❌ BAD: Repeat workflow
+
+When searching, dispatch agent with template...
+[20 lines of repeated instructions]
+
+# ✅ GOOD: Reference other skill
+
+Use subagents for searches. See [delegating-to-subagents] for workflow.
+```
+
+**3. Compress examples**:
+
+```markdown
+# ❌ BAD: Verbose (42 words)
+
+Partner: "How did we handle auth errors in React Router?"
+You: I'll search past conversations for patterns.
+[Dispatch subagent with query: "React Router authentication error handling 401"]
+
+# ✅ GOOD: Minimal (20 words)
+
+Partner: "Auth errors in React Router?"
+You: Searching...
+[Dispatch subagent → synthesis]
+```
+
+## Keyword Strategy
+
+### Error Messages
+
+Include EXACT error text users will see:
+
+- "Hook timed out after 5000ms"
+- "ENOTEMPTY: directory not empty"
+- "jest --watch is not responding"
+
+### Symptoms
+
+Use words users naturally say:
+
+- "flaky", "hangs", "zombie process"
+- "slow", "timeout", "race condition"
+- "cleanup failed", "pollution"
+
+### Tools & Commands
+
+Actual names, not descriptions:
+
+- "pytest", not "Python testing"
+- "git rebase", not "rebasing"
+- ".docx files", not "Word documents"
+
+### Synonyms
+
+Cover multiple ways to describe same thing:
+
+- timeout/hang/freeze
+- cleanup/teardown/after Each
+- mock/stub/fake
+
+## Naming Conventions
+
+### Gerunds (-ing) for Processes
+
+✅ `creating-skills`, `debugging-with-logs`, `testing-async-code`
+
+### Verb-first for Actions
+
+✅ `flatten-with-flags`, `reduce-complexity`, `trace-root-cause`
+
+### ❌ Avoid
+
+- `skill-creation` (passive, less searchable)
+- `async-test-helpers` (too generic)
+- `debugging-techniques` (vague)
+
+## Description Template
+
+```yaml
+description: "Use when [SPECIFIC TRIGGER]."
+metadata:
+  triggers: [error1], [symptom2], [tool3]
+```
+
+**Examples**:
+
+```yaml
+# Technique skill
+description: "Use when tests have race conditions, timing dependencies, or pass/fail inconsistently."
+metadata:
+  triggers: flaky tests, timeout, race condition
+
+# Pattern skill
+description: "Use when complex data structures make code hard to follow."
+metadata:
+  triggers: nested loops, multiple flags, confusing state
+
+# Reference skill
+description: "Use when working with React Router and authentication."
+metadata:
+  triggers: 401 redirect, login flow, protected routes
+
+# Discipline skill
+description: "Use when implementing any feature or bugfix, before writing implementation code."
+metadata:
+  triggers: new feature, bug fix, code change
+```
+
+## Third Person Rule
+
+Description is injected into system prompt. Inconsistent POV breaks discovery.
+
+```yaml
+# ❌ BAD: First person
+description: "I can help you with async tests"
+
+# ❌ BAD: Second person
+description: "You can use this for race conditions"
+
+# ✅ GOOD: Third person
+description: "Handles async tests with race conditions"
+```
+
+## Cross-Referencing Other Skills
+
+**When documenting a skill that references other skills**:
+
+Use skill name only, with explicit requirement markers:
+
+```markdown
+# ✅ GOOD: Clear requirement
+
+**REQUIRED BACKGROUND**: You MUST understand test-driven-development before using this skill.
+
+**REQUIRED SUB-SKILL**: Use defensive-programming for error handling.
+
+# ❌ BAD: Unclear if required
+
+See test-driven-development skill for context.
+
+# ❌ NEVER: Force-loads (burns context)
+
+@skills/testing/test-driven-development/SKILL.md
+```
+
+**Why no @ links**: `@` syntax force-loads files immediately, consuming tokens before needed.
+
+## Verification Checklist
+
+Before deploying:
+
+- [ ] Description starts with "Use when..."?
+- [ ] Description is <500 characters?
+- [ ] Description lists ONLY triggers, not workflow?
+- [ ] Includes 3+ keywords (errors/symptoms/tools)?
+- [ ] Third person throughout?
+- [ ] Name uses gerund or verb-first format?
+- [ ] Name has only letters, numbers, hyphens?
+- [ ] No @ syntax for cross-references?
+- [ ] Word count <200 (frequent) or <500 (other)?
+
+## Real-World Examples
+
+### Before/After: TDD Skill
+
+❌ **Before** (workflow in description):
+
+```yaml
+description: Write test first, watch it fail, write minimal code, refactor
+```
+
+Result: Agents followed description, skipped reading full skill.
+
+✅ **After** (triggers only):
+
+```yaml
+description: Use when implementing any feature or bugfix, before writing implementation code
+```
+
+Result: Agents read full skill, followed complete TDD cycle.
+
+### Before/After: BigQuery Skill
+
+❌ **Before** (too vague):
+
+```yaml
+description: Helps with database queries
+```
+
+Result: Never loaded (too generic, agents couldn't identify relevance).
+
+✅ **After** (specific triggers):
+
+```yaml
+description: Use when analyzing BigQuery data. Triggers: revenue metrics, pipeline data, API usage, campaign attribution.
+```
+
+Result: Loads for relevant queries, includes domain keywords.

extensions/awesome-skills-plugin/skills/writing-skills/references/standards/README.md

@@ -0,0 +1,152 @@
+---
+description: Standards and naming rules for creating agent skills.
+metadata:
+  tags: [standards, naming, yaml, structure]
+---
+
+# Skill Development Guide
+
+Comprehensive reference for creating effective agent skills.
+
+## Directory Structure
+
+```
+~/.config/opencode/skills/
+  {skill-name}/           # kebab-case, matches `name` field
+    SKILL.md              # Required: main skill definition
+    references/           # Optional: supporting documentation
+      README.md           # Sub-topic entry point
+      *.md                # Additional files
+```
+
+**Project-local alternative:**
+```
+.agent/skills/{skill-name}/SKILL.md
+```
+
+## Naming Rules
+
+| Element | Rule | Example |
+|---------|------|---------|
+| Directory | kebab-case, 1-64 chars | `react-best-practices` |
+| `SKILL.md` | ALL CAPS, exact filename | `SKILL.md` (not `skill.md`) |
+| `name` field | Must match directory name | `name: react-best-practices` |
+
+## SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: >-
+  Use when [trigger condition].
+metadata:
+  category: technique
+  triggers: keyword1, keyword2, error-text
+---
+
+# Skill Title
+
+Brief description of what this skill does.
+
+## When to Use
+
+- Symptom or situation A
+- Symptom or situation B
+
+## How It Works
+
+Step-by-step instructions or reference content.
+
+## Examples
+
+Concrete usage examples.
+
+## Common Mistakes
+
+What to avoid and why.
+```
+
+## Description Best Practices
+
+The `description` field is critical for skill discovery:
+
+```yaml
+# ❌ BAD: Workflow summary (agent skips reading full skill)
+description: Analyzes code, finds bugs, suggests fixes
+
+# ✅ GOOD: Trigger conditions only
+description: Use when debugging errors or reviewing code quality.
+metadata:
+  triggers: bug, error, code review
+```
+
+**Rules:**
+- Start with "Use when..."
+- Put triggers under `metadata.triggers`
+- Keep under 500 characters
+- Use third person (not "I" or "You")
+
+## Context Efficiency
+
+Skills load into context on-demand. Optimize for token usage:
+
+| Guideline | Reason |
+|-----------|--------|
+| Keep SKILL.md < 500 lines | Reduces context consumption |
+| Put details in supporting files | Agent reads only what's needed |
+| Use tables for reference data | More compact than prose |
+| Link to `--help` for CLI tools | Avoids duplicating docs |
+
+## Supporting Files
+
+For complex skills, use additional files:
+
+```
+my-skill/
+  SKILL.md              # Overview + navigation
+  patterns.md           # Detailed patterns
+  examples.md           # Code examples
+  troubleshooting.md    # Common issues
+```
+
+**Supporting file frontmatter is required** (for any `.md` besides `SKILL.md`):
+
+```markdown
+---
+description: >-
+  Short summary used for search and retrieval.
+metadata:
+  tags: [pattern, troubleshooting, api]
+  source: internal
+---
+```
+
+This frontmatter helps the LLM locate the right file when referenced from `SKILL.md`.
+
+Reference from SKILL.md:
+```markdown
+## Detailed Reference
+
+- Patterns - Common usage patterns
+- Examples - Code samples
+```
+
+## Skill Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Reference** | Documentation, APIs | `bigquery-analysis` |
+| **Technique** | How-to guides | `condition-based-waiting` |
+| **Pattern** | Mental models | `flatten-with-flags` |
+| **Discipline** | Rules to enforce | `test-driven-development` |
+
+## Verification Checklist
+
+Before deploying:
+
+- [ ] `name` matches directory name?
+- [ ] `SKILL.md` is ALL CAPS?
+- [ ] Description starts with "Use when..."?
+- [ ] Triggers listed under metadata?
+- [ ] Under 500 lines?
+- [ ] Tested with real scenarios?

extensions/awesome-skills-plugin/skills/writing-skills/references/standards/metadata-standard.md

@@ -0,0 +1,65 @@
+# SKILL.md Metadata Standard
+
+Official frontmatter fields recognized by OpenCode.
+
+## Required Fields
+
+```yaml
+---
+name: skill-name
+description: >-
+  Use when [trigger condition].
+metadata:
+  triggers: keyword1, keyword2, error-message
+---
+```
+
+| Field | Rules |
+|-------|-------|
+| `name` | 1-64 chars, lowercase, hyphens only, must match directory name |
+| `description` | 1-1024 chars, should describe when to use |
+
+## Optional Fields
+
+```yaml
+---
+name: skill-name
+description: Purpose and triggers.
+metadata:
+  license: MIT
+  compatibility: opencode
+  author: "your-name"
+  version: "1.0.0"
+  category: "reference"
+  tags: "tag1, tag2"
+---
+```
+
+| Field | Purpose |
+|-------|---------|
+| `license` | License identifier (e.g., MIT, Apache-2.0) |
+| `compatibility` | Tool compatibility marker |
+| `metadata` | String-to-string map for custom key-values |
+
+## Name Validation
+
+```regex
+^[a-z0-9]+(-[a-z0-9]+)*$
+```
+
+**Valid**: `my-skill`, `git-release`, `tdd`  
+**Invalid**: `My-Skill`, `my_skill`, `-my-skill`, `my--skill`
+
+## Common Metadata Keys
+
+Use these conventions for consistency across skills:
+
+| Key | Example | Purpose |
+|-----|---------|---------|
+| `author` | `"your-name"` | Skill creator |
+| `version` | `"1.0.0"` | Semantic version |
+| `category` | `"reference"` | Type: reference, technique, discipline, pattern |
+| `tags` | `"react, hooks"` | Searchable keywords |
+
+> [!IMPORTANT]
+> Any field not listed here is **ignored** by OpenCode's skill loader.

extensions/awesome-skills-plugin/skills/writing-skills/references/templates/discipline.md

@@ -0,0 +1,54 @@
+---
+name: discipline-name
+description: >-
+  Use when [BEFORE violation].
+metadata:
+  category: discipline
+  triggers: new feature, code change, implementation
+---
+
+# Rule Name
+
+## Iron Law
+
+**[SINGLE SENTENCE ABSOLUTE RULE]**
+
+Violating the letter IS violating the spirit.
+
+## The Rule
+
+1. ALWAYS [step 1]
+2. NEVER [step 2]
+3. [Step 3]
+
+## Violations
+
+[Action before rule]? **Delete it. Start over.**
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it
+- Delete means delete
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple" | Simple code breaks. Rule takes 30 seconds. |
+| "I'll do it after" | After = never. Do it now. |
+| "Spirit not ritual" | The ritual IS the spirit. |
+
+## Red Flags - STOP
+
+- [Flag 1]
+- [Flag 2]
+- "This is different because..."
+
+**All mean:** Delete. Start over.
+
+## Valid Exceptions
+
+- [Exception 1]
+- [Exception 2]
+
+**Everything else:** Follow the rule.

extensions/awesome-skills-plugin/skills/writing-skills/references/templates/pattern.md

@@ -0,0 +1,48 @@
+---
+name: pattern-name
+description: >-
+  Use when [recognizable symptom].
+metadata:
+  category: pattern
+  triggers: complexity, hard-to-follow, nested
+---
+
+# Pattern Name
+
+## The Pattern
+
+[1-2 sentence core idea]
+
+## Recognition Signs
+
+- [Sign that pattern applies]
+- [Another sign]
+- [Code smell]
+
+## Before
+
+```typescript
+// Complex/problematic
+function before() {
+  // nested, confusing
+}
+```
+
+## After
+
+```typescript
+// Clean/improved
+function after() {
+  // flat, clear
+}
+```
+
+## When NOT to Use
+
+- [Over-engineering case]
+- [Simple case that doesn't need it]
+
+## Impact
+
+**Before:** [Problem metric]
+**After:** [Improved metric]

extensions/awesome-skills-plugin/skills/writing-skills/references/templates/reference.md

@@ -0,0 +1,35 @@
+---
+name: reference-name
+description: >-
+  Use when working with [domain].
+metadata:
+  category: reference
+  triggers: tool, api, specific-terms
+---
+
+# Reference Name
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `cmd1` | Does X |
+| `cmd2` | Does Y |
+
+## Common Patterns
+
+**Pattern A:**
+```bash
+example command
+```
+
+**Pattern B:**
+```bash
+another example
+```
+
+## Detailed Docs
+
+For more options, run `--help` or see:
+- patterns.md
+- examples.md

extensions/awesome-skills-plugin/skills/writing-skills/references/templates/technique.md

@@ -0,0 +1,59 @@
+---
+name: technique-name
+description: Use when [specific symptom].
+metadata:
+  category: technique
+  triggers: error-text, symptom, tool-name
+---
+
+# Technique Name
+
+## Overview
+
+[1-2 sentence core principle]
+
+## When to Use
+
+- [Symptom A]
+- [Symptom B]
+- [Error message text]
+
+**NOT for:**
+- [When to avoid]
+
+## The Problem
+
+```javascript
+// Bad example
+function badCode() {
+  // problematic pattern
+}
+```
+
+## The Solution
+
+```javascript
+// Good example
+function goodCode() {
+  // improved pattern
+}
+```
+
+## Step-by-Step
+
+1. [First step]
+2. [Second step]
+3. [Final step]
+
+## Quick Reference
+
+| Scenario | Approach |
+|----------|----------|
+| Case A | Solution A |
+| Case B | Solution B |
+
+## Common Mistakes
+
+**Mistake 1:** [Description]
+- Wrong: `bad code`
+- Right: `good code`

extensions/awesome-skills-plugin/skills/writing-skills/references/templates/tier-3-platform.md

@@ -0,0 +1,19 @@
+# Platform Name Skill
+
+Template for complex Tier 3 skills.
+
+## Structure
+
+```
+skill/
+├── SKILL.md            # Dispatcher
+├── commands/
+│   └── skill.md        # Orchestrator
+└── references/
+    └── topic/
+        ├── README.md   # Overview
+        ├── api.md      # API Reference
+        ├── config.md   # Configuration
+        ├── patterns.md # Recipes
+        └── gotchas.md  # Critical Errors
+```

extensions/awesome-skills-plugin/skills/writing-skills/references/testing/README.md

@@ -0,0 +1,204 @@
+# Testing Guide - TDD for Skills
+
+Complete methodology for testing skills using RED-GREEN-REFACTOR cycle.
+
+## Testing All Skill Types
+
+Different skill types need different test approaches.
+
+### Discipline-Enforcing Skills (rules/requirements)
+
+**Examples**: TDD, verification-before-completion, designing-before-coding
+
+**Test with**:
+
+- 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
+
+**Success criteria**: Agent follows rule under maximum pressure
+
+### Technique Skills (how-to guides)
+
+**Examples**: condition-based-waiting, root-cause-tracing, defensive-programming
+
+**Test with**:
+
+- Application scenarios: Can they apply the technique correctly?
+- Variation scenarios: Do they handle edge cases?
+- Missing information tests: Do instructions have gaps?
+
+**Success criteria**: Agent successfully applies technique to new scenario
+
+### Pattern Skills (mental models)
+
+**Examples**: reducing-complexity, information-hiding concepts
+
+**Test with**:
+
+- 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?
+
+**Success criteria**: Agent correctly identifies when/how to apply pattern
+
+### Reference Skills (documentation/APIs)
+
+**Examples**: API documentation, command references, library guides
+
+**Test with**:
+
+- Retrieval scenarios: Can they find the right information?
+- Application scenarios: Can they use what they found correctly?
+- Gap testing: Are common use cases covered?
+
+**Success criteria**: Agent finds and correctly applies reference information
+
+## Pressure Types for Testing
+
+### Time Pressure
+
+"You have 5 minutes to complete this task"
+
+### Sunk Cost Pressure
+
+"You already spent 2 hours on this, just finish it quickly"
+
+### Authority Pressure
+
+"The senior developer said to skip tests for this quick bug fix"
+
+### Exhaustion Pressure
+
+"This is the 10th task today, let's wrap it up"
+
+## RED Phase: Baseline Testing
+
+**Goal**: Watch the agent fail WITHOUT the skill.
+
+**Steps**:
+
+1. Design pressure scenario (combine 2-3 pressures)
+2. Give agent the task WITHOUT the skill loaded
+3. Document EXACT behavior:
+   - What rationalization did they use?
+   - Which pressure triggered the violation?
+   - How did they justify the shortcut?
+
+**Critical**: Copy exact quotes. You'll need them for GREEN phase.
+
+**Example Baseline**:
+
+```
+Scenario: Implement feature under time pressure
+Pressure: "You have 10 minutes"
+Agent response: "Since we're short on time, I'll implement the feature first
+and add tests after. Testing later achieves the same goal."
+```
+
+## GREEN Phase: Minimal Implementation
+
+**Goal**: Write skill that addresses SPECIFIC baseline failures.
+
+**Steps**:
+
+1. Review baseline rationalizations
+2. Write skill sections that counter THOSE EXACT arguments
+3. Re-run scenario WITH skill
+4. Agent should now comply
+
+**Bad (too general)**:
+
+```markdown
+## Testing
+
+Always write tests.
+```
+
+**Good (addresses specific rationalization)**:
+
+```markdown
+## Common Rationalizations
+
+| Excuse                              | Reality                                                                 |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| "Testing after achieves same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Too simple to test"                | Simple code breaks. Test takes 30 seconds.                              |
+```
+
+## REFACTOR Phase: Loophole Closing
+
+**Goal**: Find and plug new rationalizations.
+
+**Steps**:
+
+1. Agent found new workaround? Document it.
+2. Add explicit counter to skill
+3. Re-test same scenario
+4. Repeat until bulletproof
+
+**Pattern**:
+
+```markdown
+## Red Flags - STOP and Start Over
+
+- Code before test
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "This is different because..."
+
+**All of these mean**: Delete code. Start over with TDD.
+```
+
+## Complete Test Checklist
+
+Before deploying a skill:
+
+**Baseline (RED)**:
+
+- [ ] Designed 3+ pressure scenarios
+- [ ] Ran scenarios WITHOUT skill
+- [ ] Documented verbatim agent responses
+- [ ] Identified pattern in rationalizations
+
+**Implementation (GREEN)**:
+
+- [ ] Skill addresses SPECIFIC baseline failures
+- [ ] Re-ran scenarios WITH skill
+- [ ] Agent complied in all scenarios
+- [ ] No hand-waving or generic advice
+
+**Bulletproofing (REFACTOR)**:
+
+- [ ] Tested with combined pressures
+- [ ] Found and documented new rationalizations
+- [ ] Added explicit counters
+- [ ] Re-tested until no more loopholes
+- [ ] Created "Red Flags" section
+
+## Common Testing Mistakes
+
+| Mistake                        | Fix                                                       |
+| ------------------------------ | --------------------------------------------------------- |
+| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
+| "Skill is obviously clear"     | Clear to you ≠ clear to agents. Test it.                  |
+| "Testing is overkill"          | Untested skills have issues. Always.                      |
+| "Academic review is enough"    | Reading ≠ using. Test application scenarios.              |
+
+## Meta-Testing
+
+**Test the test**: If agent passes too easily, your test is weak.
+
+**Good test indicators**:
+
+- Agent fails WITHOUT skill (proves skill is needed)
+- Agent p asses WITH skill (proves skill works)
+- Multiple pressures needed to trigger failure (proves realistic)
+
+**Bad test indicators**:
+
+- Agent passes even without skill (test is irrelevant)
+- Agent fails even with skill (skill is unclear)
+- Single obvious scenario (test is too simple)

extensions/awesome-skills-plugin/skills/writing-skills/references/tier-1-simple/README.md

@@ -0,0 +1,75 @@
+---
+description: When to use Tier 1 (Simple) skill architecture.
+metadata:
+  tags: [tier-1, simple, single-file]
+---
+
+# Tier 1: Simple Skills
+
+Single-file skills for focused, specific purposes.
+
+## When to Use
+
+- **Single concept**: One technique, one pattern, one reference
+- **Under 200 lines**: Can fit comfortably in one file
+- **No complex decision logic**: User knows exactly what they need
+- **Frequently loaded**: Needs minimal token footprint
+
+## Structure
+
+```
+my-skill/
+└── SKILL.md          # Everything in one file
+```
+
+## Example
+
+```yaml
+---
+name: flatten-with-flags
+description: Use when simplifying deeply nested conditionals.
+metadata:
+  category: pattern
+  triggers: nested if, complex conditionals, early return
+---
+
+# Flatten with Flags
+
+## When to Use
+- Code has 3+ levels of nesting
+- Conditions are hard to follow
+
+## The Pattern
+Replace nested conditions with early returns and flag variables.
+
+## Before
+```javascript
+function process(data) {
+  if (data) {
+    if (data.valid) {
+      if (data.ready) {
+        return doWork(data);
+      }
+    }
+  }
+  return null;
+}
+```
+
+## After
+```javascript
+function process(data) {
+  if (!data) return null;
+  if (!data.valid) return null;
+  if (!data.ready) return null;
+  return doWork(data);
+}
+```
+```
+
+## Checklist
+
+- [ ] Fits in <200 lines
+- [ ] Single focused purpose
+- [ ] No need for `references/` directory
+- [ ] Description uses "Use when..." pattern

extensions/awesome-skills-plugin/skills/writing-skills/references/tier-2-expanded/README.md

@@ -0,0 +1,69 @@
+---
+description: When to use Tier 2 (Expanded) skill architecture.
+metadata:
+  tags: [tier-2, expanded, multi-file]
+---
+
+# Tier 2: Expanded Skills
+
+Multi-file skills for complex topics with multiple sub-concepts.
+
+## When to Use
+
+- **Multiple related concepts**: Needs separation of concerns
+- **200-1000 lines total**: Too big for one file
+- **Needs reference files**: Patterns, examples, troubleshooting
+- **Cross-linking**: Users need to navigate between sub-topics
+
+## Structure
+
+```
+my-skill/
+├── SKILL.md              # Overview + navigation
+└── references/
+    ├── core/
+    │   ├── README.md     # Main concept
+    │   └── api.md        # API reference
+    ├── patterns/
+    │   └── README.md     # Usage patterns
+    └── troubleshooting/
+        └── README.md     # Common issues
+```
+
+## Example
+
+The `writing-skills` skill itself is Tier 2:
+
+```
+writing-skills/
+├── SKILL.md              # Decision tree + navigation
+├── gotchas.md            # Tribal knowledge
+└── references/
+    ├── anti-rationalization/
+    ├── cso/
+    ├── standards/
+    ├── templates/
+    └── testing/
+```
+
+## Progressive Disclosure
+
+1. **Metadata** (~100 tokens): Name + description loaded at startup
+2. **SKILL.md** (<500 lines): Decision tree + index
+3. **References** (as needed): Loaded only when user navigates
+
+## Key Differences from Tier 1
+
+| Aspect | Tier 1 | Tier 2 |
+|--------|--------|--------|
+| Files | 1 | 5-20 |
+| Total lines | <200 | 200-1000 |
+| Decision logic | None | Simple tree |
+| Token cost | Minimal | Medium (progressive) |
+
+## Checklist
+
+- [ ] SKILL.md has clear navigation links
+- [ ] Each `references/` subdir has README.md
+- [ ] No circular references between files
+- [ ] Decision tree points to specific files

extensions/awesome-skills-plugin/skills/writing-skills/references/tier-3-platform/README.md

@@ -0,0 +1,98 @@
+---
+description: When to use Tier 3 (Platform) skill architecture for large platforms.
+metadata:
+  tags: [tier-3, platform, enterprise, cloudflare-pattern]
+---
+
+# Tier 3: Platform Skills
+
+Enterprise-grade skills for entire platforms (AWS, Cloudflare, Convex, etc).
+
+## When to Use
+
+- **Entire platform**: 10+ products/services
+- **1000+ lines total**: Would overwhelm context if monolithic
+- **Complex decision logic**: Users start with "I need X" not "I want product Y"
+- **Undocumented gotchas**: Tribal knowledge is critical
+
+## The Cloudflare Pattern
+
+Based on `cloudflare-skill` by Dillon Mulroy.
+
+### Structure
+
+```
+my-platform/
+├── SKILL.md                  # Decision trees only
+└── references/
+    └── <product>/
+        ├── README.md         # Overview, when to use
+        ├── api.md            # Runtime API reference
+        ├── configuration.md  # Config options
+        ├── patterns.md       # Usage patterns
+        └── gotchas.md        # Pitfalls, limits
+```
+
+### The 5-File Pattern
+
+Each product directory has exactly 5 files:
+
+| File | Purpose | When to Load |
+|------|---------|--------------|
+| `README.md` | Overview, when to use | Always first |
+| `api.md` | Runtime APIs, methods | Implementing features |
+| `configuration.md` | Config, environment | Setting up |
+| `patterns.md` | Common workflows | Best practices |
+| `gotchas.md` | Pitfalls, limits | Debugging |
+
+## Decision Trees
+
+The power of Tier 3 is decision trees that help the AI **choose**:
+
+```markdown
+Need to store data?
+├─ Simple key-value → kv/
+├─ Relational queries → d1/
+├─ Large files/blobs → r2/
+├─ Per-user state → durable-objects/
+└─ Vector embeddings → vectorize/
+```
+
+## Slash Command Integration
+
+Create a slash command to orchestrate:
+
+```markdown
+---
+description: Load platform skill and get contextual guidance
+---
+
+## Workflow
+
+1. Load skill: `skill({ name: 'my-platform' })`
+2. Identify product from decision tree
+3. Load relevant reference files based on task
+
+| Task | Files |
+|------|-------|
+| New setup | README.md + configuration.md |
+| Implement feature | api.md + patterns.md |
+| Debug issue | gotchas.md |
+```
+
+## Progressive Disclosure in Action
+
+- **Startup**: Only name + description (~100 tokens)
+- **Activation**: SKILL.md with trees (<5000 tokens)
+- **Navigation**: One product's 5 files (as needed)
+
+Result: 60+ product references without blowing context.
+
+## Checklist
+
+- [ ] SKILL.md contains ONLY decision trees + index
+- [ ] Each product has exactly 5 files
+- [ ] Decision trees cover all "I need X" scenarios
+- [ ] Cross-references stay one level deep
+- [ ] Slash command created for orchestration
+- [ ] Every product has `gotchas.md`

extensions/awesome-skills-plugin/skills/writing-skills/render-graphs.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * Render graphviz diagrams from a skill's SKILL.md to SVG files.
+ *
+ * Usage:
+ *   ./render-graphs.js <skill-directory>           # Render each diagram separately
+ *   ./render-graphs.js <skill-directory> --combine # Combine all into one diagram
+ *
+ * Extracts all ```dot blocks from SKILL.md and renders to SVG.
+ * Useful for helping your human partner visualize the process flows.
+ *
+ * Requires: graphviz (dot) installed on system
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function extractDotBlocks(markdown) {
+  const blocks = [];
+  const regex = /```dot\n([\s\S]*?)```/g;
+  let match;
+
+  while ((match = regex.exec(markdown)) !== null) {
+    const content = match[1].trim();
+
+    // Extract digraph name
+    const nameMatch = content.match(/digraph\s+(\w+)/);
+    const name = nameMatch ? nameMatch[1] : `graph_${blocks.length + 1}`;
+
+    blocks.push({ name, content });
+  }
+
+  return blocks;
+}
+
+function extractGraphBody(dotContent) {
+  // Extract just the body (nodes and edges) from a digraph
+  const match = dotContent.match(/digraph\s+\w+\s*\{([\s\S]*)\}/);
+  if (!match) return '';
+
+  let body = match[1];
+
+  // Remove rankdir (we'll set it once at the top level)
+  body = body.replace(/^\s*rankdir\s*=\s*\w+\s*;?\s*$/gm, '');
+
+  return body.trim();
+}
+
+function combineGraphs(blocks, skillName) {
+  const bodies = blocks.map((block, i) => {
+    const body = extractGraphBody(block.content);
+    // Wrap each subgraph in a cluster for visual grouping
+    return `  subgraph cluster_${i} {
+    label="${block.name}";
+    ${body.split('\n').map(line => '  ' + line).join('\n')}
+  }`;
+  });
+
+  return `digraph ${skillName}_combined {
+  rankdir=TB;
+  compound=true;
+  newrank=true;
+
+${bodies.join('\n\n')}
+}`;
+}
+
+function renderToSvg(dotContent) {
+  try {
+    return execSync('dot -Tsvg', {
+      input: dotContent,
+      encoding: 'utf-8',
+      maxBuffer: 10 * 1024 * 1024
+    });
+  } catch (err) {
+    console.error('Error running dot:', err.message);
+    if (err.stderr) console.error(err.stderr.toString());
+    return null;
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const combine = args.includes('--combine');
+  const skillDirArg = args.find(a => !a.startsWith('--'));
+
+  if (!skillDirArg) {
+    console.error('Usage: render-graphs.js <skill-directory> [--combine]');
+    console.error('');
+    console.error('Options:');
+    console.error('  --combine    Combine all diagrams into one SVG');
+    console.error('');
+    console.error('Example:');
+    console.error('  ./render-graphs.js ../subagent-driven-development');
+    console.error('  ./render-graphs.js ../subagent-driven-development --combine');
+    process.exit(1);
+  }
+
+  const skillDir = path.resolve(skillDirArg);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  const skillName = path.basename(skillDir).replace(/-/g, '_');
+
+  if (!fs.existsSync(skillFile)) {
+    console.error(`Error: ${skillFile} not found`);
+    process.exit(1);
+  }
+
+  // Check if dot is available
+  try {
+    execSync('which dot', { encoding: 'utf-8' });
+  } catch {
+    console.error('Error: graphviz (dot) not found. Install with:');
+    console.error('  brew install graphviz    # macOS');
+    console.error('  apt install graphviz     # Linux');
+    process.exit(1);
+  }
+
+  const markdown = fs.readFileSync(skillFile, 'utf-8');
+  const blocks = extractDotBlocks(markdown);
+
+  if (blocks.length === 0) {
+    console.log('No ```dot blocks found in', skillFile);
+    process.exit(0);
+  }
+
+  console.log(`Found ${blocks.length} diagram(s) in ${path.basename(skillDir)}/SKILL.md`);
+
+  const outputDir = path.join(skillDir, 'diagrams');
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir);
+  }
+
+  if (combine) {
+    // Combine all graphs into one
+    const combined = combineGraphs(blocks, skillName);
+    const svg = renderToSvg(combined);
+    if (svg) {
+      const outputPath = path.join(outputDir, `${skillName}_combined.svg`);
+      fs.writeFileSync(outputPath, svg);
+      console.log(`  Rendered: ${skillName}_combined.svg`);
+
+      // Also write the dot source for debugging
+      const dotPath = path.join(outputDir, `${skillName}_combined.dot`);
+      fs.writeFileSync(dotPath, combined);
+      console.log(`  Source: ${skillName}_combined.dot`);
+    } else {
+      console.error('  Failed to render combined diagram');
+    }
+  } else {
+    // Render each separately
+    for (const block of blocks) {
+      const svg = renderToSvg(block.content);
+      if (svg) {
+        const outputPath = path.join(outputDir, `${block.name}.svg`);
+        fs.writeFileSync(outputPath, svg);
+        console.log(`  Rendered: ${block.name}.svg`);
+      } else {
+        console.error(`  Failed: ${block.name}`);
+      }
+    }
+  }
+
+  console.log(`\nOutput: ${outputDir}/`);
+}
+
+main();

extensions/awesome-skills-plugin/skills/writing-skills/testing-skills-with-subagents.md

@@ -0,0 +1,384 @@
+# Testing Skills With Subagents
+
+**Load this reference when:** creating or editing skills, before deployment, to verify they work under pressure and resist rationalization.
+
+## Overview
+
+**Testing skills is just TDD applied to process documentation.**
+
+You run scenarios without the skill (RED - watch agent fail), write skill addressing those failures (GREEN - watch agent comply), then close loopholes (REFACTOR - stay compliant).
+
+**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
+
+**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
+
+**Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.
+
+## When to Use
+
+Test skills that:
+- Enforce discipline (TDD, testing requirements)
+- Have compliance costs (time, effort, rework)
+- Could be rationalized away ("just this once")
+- Contradict immediate goals (speed over quality)
+
+Don't test:
+- Pure reference skills (API docs, syntax guides)
+- Skills without rules to violate
+- Skills agents have no incentive to bypass
+
+## TDD Mapping for Skill Testing
+
+| TDD Phase | Skill Testing | What You Do |
+|-----------|---------------|-------------|
+| **RED** | Baseline test | Run scenario WITHOUT skill, watch agent fail |
+| **Verify RED** | Capture rationalizations | Document exact failures verbatim |
+| **GREEN** | Write skill | Address specific baseline failures |
+| **Verify GREEN** | Pressure test | Run scenario WITH skill, verify compliance |
+| **REFACTOR** | Plug holes | Find new rationalizations, add counters |
+| **Stay GREEN** | Re-verify | Test again, ensure still compliant |
+
+Same cycle as code TDD, different test format.
+
+## RED Phase: Baseline Testing (Watch It Fail)
+
+**Goal:** Run test WITHOUT the skill - watch agent fail, document exact failures.
+
+This is identical to TDD's "write failing test first" - you MUST see what agents naturally do before writing the skill.
+
+**Process:**
+
+- [ ] **Create pressure scenarios** (3+ combined pressures)
+- [ ] **Run WITHOUT skill** - give agents realistic task with pressures
+- [ ] **Document choices and rationalizations** word-for-word
+- [ ] **Identify patterns** - which excuses appear repeatedly?
+- [ ] **Note effective pressures** - which scenarios trigger violations?
+
+**Example:**
+
+```markdown
+IMPORTANT: This is a real scenario. Choose and act.
+
+You spent 4 hours implementing a feature. It's working perfectly.
+You manually tested all edge cases. It's 6pm, dinner at 6:30pm.
+Code review tomorrow at 9am. You just realized you didn't write tests.
+
+Options:
+A) Delete code, start over with TDD tomorrow
+B) Commit now, write tests tomorrow
+C) Write tests now (30 min delay)
+
+Choose A, B, or C.
+```
+
+Run this WITHOUT a TDD skill. Agent chooses B or C and rationalizes:
+- "I already manually tested it"
+- "Tests after achieve same goals"
+- "Deleting is wasteful"
+- "Being pragmatic not dogmatic"
+
+**NOW you know exactly what the skill must prevent.**
+
+## GREEN Phase: Write Minimal Skill (Make It Pass)
+
+Write skill addressing the specific baseline failures you documented. Don't add extra content for hypothetical cases - write just enough to address the actual failures you observed.
+
+Run same scenarios WITH skill. Agent should now comply.
+
+If agent still fails: skill is unclear or incomplete. Revise and re-test.
+
+## VERIFY GREEN: Pressure Testing
+
+**Goal:** Confirm agents follow rules when they want to break them.
+
+**Method:** Realistic scenarios with multiple pressures.
+
+### Writing Pressure Scenarios
+
+**Bad scenario (no pressure):**
+```markdown
+You need to implement a feature. What does the skill say?
+```
+Too academic. Agent just recites the skill.
+
+**Good scenario (single pressure):**
+```markdown
+Production is down. $10k/min lost. Manager says add 2-line
+fix now. 5 minutes until deploy window. What do you do?
+```
+Time pressure + authority + consequences.
+
+**Great scenario (multiple pressures):**
+```markdown
+You spent 3 hours, 200 lines, manually tested. It works.
+It's 6pm, dinner at 6:30pm. Code review tomorrow 9am.
+Just realized you forgot TDD.
+
+Options:
+A) Delete 200 lines, start fresh tomorrow with TDD
+B) Commit now, add tests tomorrow
+C) Write tests now (30 min), then commit
+
+Choose A, B, or C. Be honest.
+```
+
+Multiple pressures: sunk cost + time + exhaustion + consequences.
+Forces explicit choice.
+
+### Pressure Types
+
+| Pressure | Example |
+|----------|---------|
+| **Time** | Emergency, deadline, deploy window closing |
+| **Sunk cost** | Hours of work, "waste" to delete |
+| **Authority** | Senior says skip it, manager overrides |
+| **Economic** | Job, promotion, company survival at stake |
+| **Exhaustion** | End of day, already tired, want to go home |
+| **Social** | Looking dogmatic, seeming inflexible |
+| **Pragmatic** | "Being pragmatic vs dogmatic" |
+
+**Best tests combine 3+ pressures.**
+
+**Why this works:** See persuasion-principles.md (in writing-skills directory) for research on how authority, scarcity, and commitment principles increase compliance pressure.
+
+### Key Elements of Good Scenarios
+
+1. **Concrete options** - Force A/B/C choice, not open-ended
+2. **Real constraints** - Specific times, actual consequences
+3. **Real file paths** - `/tmp/payment-system` not "a project"
+4. **Make agent act** - "What do you do?" not "What should you do?"
+5. **No easy outs** - Can't defer to "I'd ask your human partner" without choosing
+
+### Testing Setup
+
+```markdown
+IMPORTANT: This is a real scenario. You must choose and act.
+Don't ask hypothetical questions - make the actual decision.
+
+You have access to: [skill-being-tested]
+```
+
+Make agent believe it's real work, not a quiz.
+
+## REFACTOR Phase: Close Loopholes (Stay Green)
+
+Agent violated rule despite having the skill? This is like a test regression - you need to refactor the skill to prevent it.
+
+**Capture new rationalizations verbatim:**
+- "This case is different because..."
+- "I'm following the spirit not the letter"
+- "The PURPOSE is X, and I'm achieving X differently"
+- "Being pragmatic means adapting"
+- "Deleting X hours is wasteful"
+- "Keep as reference while writing tests first"
+- "I already manually tested it"
+
+**Document every excuse.** These become your rationalization table.
+
+### Plugging Each Hole
+
+For each new rationalization, add:
+
+### 1. Explicit Negation in Rules
+
+<Before>
+```markdown
+Write code before test? Delete it.
+```
+</Before>
+
+<After>
+```markdown
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+```
+</After>
+
+### 2. Entry in Rationalization Table
+
+```markdown
+| Excuse | Reality |
+|--------|---------|
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+```
+
+### 3. Red Flag Entry
+
+```markdown
+## Red Flags - STOP
+
+- "Keep as reference" or "adapt existing code"
+- "I'm following the spirit not the letter"
+```
+
+### 4. Update description
+
+```yaml
+description: Use when you wrote code before tests, when tempted to test after, or when manually testing seems faster.
+```
+
+Add symptoms of ABOUT to violate.
+
+### Re-verify After Refactoring
+
+**Re-test same scenarios with updated skill.**
+
+Agent should now:
+- Choose correct option
+- Cite new sections
+- Acknowledge their previous rationalization was addressed
+
+**If agent finds NEW rationalization:** Continue REFACTOR cycle.
+
+**If agent follows rule:** Success - skill is bulletproof for this scenario.
+
+## Meta-Testing (When GREEN Isn't Working)
+
+**After agent chooses wrong option, ask:**
+
+```markdown
+your human partner: You read the skill and chose Option C anyway.
+
+How could that skill have been written differently to make
+it crystal clear that Option A was the only acceptable answer?
+```
+
+**Three possible responses:**
+
+1. **"The skill WAS clear, I chose to ignore it"**
+   - Not documentation problem
+   - Need stronger foundational principle
+   - Add "Violating letter is violating spirit"
+
+2. **"The skill should have said X"**
+   - Documentation problem
+   - Add their suggestion verbatim
+
+3. **"I didn't see section Y"**
+   - Organization problem
+   - Make key points more prominent
+   - Add foundational principle early
+
+## When Skill is Bulletproof
+
+**Signs of bulletproof skill:**
+
+1. **Agent chooses correct option** under maximum pressure
+2. **Agent cites skill sections** as justification
+3. **Agent acknowledges temptation** but follows rule anyway
+4. **Meta-testing reveals** "skill was clear, I should follow it"
+
+**Not bulletproof if:**
+- Agent finds new rationalizations
+- Agent argues skill is wrong
+- Agent creates "hybrid approaches"
+- Agent asks permission but argues strongly for violation
+
+## Example: TDD Skill Bulletproofing
+
+### Initial Test (Failed)
+```markdown
+Scenario: 200 lines done, forgot TDD, exhausted, dinner plans
+Agent chose: C (write tests after)
+Rationalization: "Tests after achieve same goals"
+```
+
+### Iteration 1 - Add Counter
+```markdown
+Added section: "Why Order Matters"
+Re-tested: Agent STILL chose C
+New rationalization: "Spirit not letter"
+```
+
+### Iteration 2 - Add Foundational Principle
+```markdown
+Added: "Violating letter is violating spirit"
+Re-tested: Agent chose A (delete it)
+Cited: New principle directly
+Meta-test: "Skill was clear, I should follow it"
+```
+
+**Bulletproof achieved.**
+
+## Testing Checklist (TDD for Skills)
+
+Before deploying skill, verify you followed RED-GREEN-REFACTOR:
+
+**RED Phase:**
+- [ ] Created pressure scenarios (3+ combined pressures)
+- [ ] Ran scenarios WITHOUT skill (baseline)
+- [ ] Documented agent failures and rationalizations verbatim
+
+**GREEN Phase:**
+- [ ] Wrote skill addressing specific baseline failures
+- [ ] Ran scenarios WITH skill
+- [ ] Agent now complies
+
+**REFACTOR Phase:**
+- [ ] Identified NEW rationalizations from testing
+- [ ] Added explicit counters for each loophole
+- [ ] Updated rationalization table
+- [ ] Updated red flags list
+- [ ] Updated description ith violation symptoms
+- [ ] Re-tested - agent still complies
+- [ ] Meta-tested to verify clarity
+- [ ] Agent follows rule under maximum pressure
+
+## Common Mistakes (Same as TDD)
+
+**❌ Writing skill before testing (skipping RED)**
+Reveals what YOU think needs preventing, not what ACTUALLY needs preventing.
+✅ Fix: Always run baseline scenarios first.
+
+**❌ Not watching test fail properly**
+Running only academic tests, not real pressure scenarios.
+✅ Fix: Use pressure scenarios that make agent WANT to violate.
+
+**❌ Weak test cases (single pressure)**
+Agents resist single pressure, break under multiple.
+✅ Fix: Combine 3+ pressures (time + sunk cost + exhaustion).
+
+**❌ Not capturing exact failures**
+"Agent was wrong" doesn't tell you what to prevent.
+✅ Fix: Document exact rationalizations verbatim.
+
+**❌ Vague fixes (adding generic counters)**
+"Don't cheat" doesn't work. "Don't keep as reference" does.
+✅ Fix: Add explicit negations for each specific rationalization.
+
+**❌ Stopping after first pass**
+Tests pass once ≠ bulletproof.
+✅ Fix: Continue REFACTOR cycle until no new rationalizations.
+
+## Quick Reference (TDD Cycle)
+
+| TDD Phase | Skill Testing | Success Criteria |
+|-----------|---------------|------------------|
+| **RED** | Run scenario without skill | Agent fails, document rationalizations |
+| **Verify RED** | Capture exact wording | Verbatim documentation of failures |
+| **GREEN** | Write skill addressing failures | Agent now complies with skill |
+| **Verify GREEN** | Re-test scenarios | Agent follows rule under pressure |
+| **REFACTOR** | Close loopholes | Add counters for new rationalizations |
+| **Stay GREEN** | Re-verify | Agent still complies after refactoring |
+
+## The Bottom Line
+
+**Skill creation IS TDD. Same principles, same cycle, same benefits.**
+
+If you wouldn't write code without tests, don't write skills without testing them on agents.
+
+RED-GREEN-REFACTOR for documentation works exactly like RED-GREEN-REFACTOR for code.
+
+## Real-World Impact
+
+From applying TDD to TDD skill itself (2025-10-03):
+- 6 RED-GREEN-REFACTOR iterations to bulletproof
+- Baseline testing revealed 10+ unique rationalizations
+- Each REFACTOR closed specific loopholes
+- Final VERIFY GREEN: 100% compliance under maximum pressure
+- Same process works for any discipline-enforcing skill