thachvd-kit 1.0.18 → 1.0.20

package/skills/writing-skills/SKILL.md

@@ -1,110 +1,170 @@
----
-name: writing-skills
-description: Use when creating a new skill or improving an existing one — follows best practices for SKILL.md structure, Claude Search Optimization, token efficiency, and skill testing methodology
-allowed-tools: Read, Write, Edit
----
-
-# Writing Skills
-
-## What is a Skill?
-
-A skill is a reusable instruction set that activates when Claude detects a relevant context. It lives in a folder with a `SKILL.md` file.
-
-## Skill Types
-
-| Type | Purpose | Example |
-|------|---------|---------|
-| **Technique** | How-to guide | `tdd-workflow` |
-| **Pattern** | Mental model | `clean-code` |
-| **Reference** | Documentation | `api-patterns` |
-| **Discipline** | Rules/enforcement | `verification-before-completion` |
-
-## Directory Structure
-
-```
-skill-name/
-├── SKILL.md          # Required: metadata + instructions
-├── scripts/          # Optional: runnable scripts
-└── references/       # Optional: templates, docs
-```
-
-## SKILL.md Structure
-
-```markdown
----
-name: skill-name
-description: [Trigger description — when to use this skill]
-allowed-tools: [Bash, Read, Edit, Write, ...]
----
-
-# Skill Title
-
-## Overview
-Brief summary + core principle
-
-## [Main Content]
-...
-```
-
-## Claude Search Optimization (CSO)
-
-The `description` field is how Claude decides whether to load your skill. Make it trigger correctly:
-
-### 1. Rich Description
-
-```yaml
-# ❌ Vague
-description: For code review
-
-# ✅ Specific with triggers
-description: Use when completing tasks, implementing major features, or before merging — pre-review checklist, evidence-before-claims workflow
-```
-
-### 2. Keyword Coverage
-
-Include synonyms, trigger phrases, and common user requests in description.
-
-### 3. Token Efficiency (Critical)
-
-- Use tables instead of prose for comparisons
-- Use code blocks for commands
-- Use flowcharts/diagrams for processes
-- Avoid narrative explanations — use structured data
-
-### 4. Cross-Referencing
-
-Use `Pairs with:` and `Integration:` sections to link related skills.
-
-## Anti-Patterns to Avoid
-
-| ❌ Anti-Pattern | ✅ Fix |
-|----------------|-------|
-| Narrative prose everywhere | Tables, bullet lists, code blocks |
-| Same content in multiple languages | Pick one, note variants |
-| Code examples in flowchart labels | Flowcharts for flow, code blocks for code |
-| Generic labels ("Step 1", "Step 2") | Descriptive labels ("Verify baseline", "Create worktree") |
-| Vague description | Specific triggers and use cases |
-
-## Skill Creation Checklist
-
-- [ ] Description field triggers correctly (test with: "would Claude load this for X?")
-- [ ] Core principle stated in Overview
-- [ ] Content uses tables/code blocks, not prose paragraphs
-- [ ] Token-efficient (no redundant explanations)
-- [ ] Red Flags / Anti-Patterns section included for discipline skills
-- [ ] Integration section lists related skills
-- [ ] Tested: create a scenario where this skill should fire, verify it does
-
-## Testing Skills
-
-For **discipline skills** (rules): Create scenario where rule should fire, verify AI follows it.
-For **technique skills** (how-to): Apply skill to a real task, verify output quality.
-For **reference skills** (docs): Query for specific info, verify correct answer.
-
-## The Bottom Line
-
-A skill is good when:
-1. It fires when it should (good description/CSO)
-2. It improves output quality noticeably
-3. It's token-efficient (doesn't waste context)
-4. It has no ambiguous loopholes
+---
+name: writing-skills
+description: Use when creating a new skill or improving an existing one — follows best practices for SKILL.md structure, Claude Search Optimization, token efficiency, anti-rationalization tables, and skill testing methodology
+allowed-tools: Read, Write, Edit
+---
+
+# Writing Skills
+
+## What is a Skill?
+
+A skill is a reusable instruction set that activates when an AI detects a relevant context. It lives in a folder with a `SKILL.md` file and works across Codex, Antigravity, Claude, and Cursor.
+
+## Skill Types
+
+| Type | Purpose | Example | Anti-Rationalization Required? |
+|------|---------|---------|----|
+| **Technique** | How-to guide | `tdd-workflow` | Optional |
+| **Pattern** | Mental model | `clean-code` | Optional |
+| **Reference** | Documentation | `api-patterns` | No |
+| **Discipline** | Rules/enforcement | `verification-before-completion` | **Mandatory** |
+
+## Directory Structure
+
+```
+skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: runnable scripts
+└── references/       # Optional: templates, docs
+```
+
+## SKILL.md Structure
+
+```markdown
+---
+name: skill-name
+description: [Trigger description — when to use this skill]
+allowed-tools: [Bash, Read, Edit, Write, ...]
+---
+
+# Skill Title
+
+## Overview
+Brief summary + core principle
+
+## When to Use
+- Specific trigger scenarios
+
+## [Main Content]
+...
+
+## Anti-Rationalization  ← REQUIRED for Discipline/Technique skills
+| Excuse | Correct Response |
+|--------|-----------------|
+| "Just this once" | No exceptions. Apply the rule. |
+
+## Exit Criteria  ← REQUIRED for Technique/Discipline skills
+- [ ] Specific, verifiable condition 1
+- [ ] Specific, verifiable condition 2
+```
+
+## Claude Search Optimization (CSO)
+
+The `description` field is how the AI decides whether to load your skill. Make it trigger correctly:
+
+### 1. Rich Description
+
+```yaml
+# ❌ Vague
+description: For code review
+
+# ✅ Specific with triggers
+description: Use when completing tasks, implementing major features, or before merging — pre-review checklist, evidence-before-claims workflow
+```
+
+### 2. Keyword Coverage
+
+Include synonyms, trigger phrases, and common user requests in description.
+
+### 3. Token Efficiency (Critical)
+
+- Use tables instead of prose for comparisons
+- Use code blocks for commands
+- Use flowcharts/diagrams for processes
+- Avoid narrative explanations — use structured data
+
+### 4. Cross-Referencing
+
+Use `Pairs with:` and `Integration:` sections to link related skills.
+
+## Anti-Rationalization Tables (Key Concept)
+
+The most powerful feature of a discipline skill. A table that blocks the AI's most common excuses for skipping a rule.
+
+### Why They Matter
+
+AI agents (like humans) tend to rationalize shortcuts under pressure. An Anti-Rationalization table names each excuse explicitly and provides the correct response, making it impossible to skip without consciously overriding the rule.
+
+### Format
+
+```markdown
+## Anti-Rationalization
+
+| Excuse | Reality / Correct Response |
+|--------|---------------------------|
+| "It's a small change" | Size doesn't reduce the need. Apply the rule. |
+| "I'm confident it works" | Confidence ≠ evidence. Run verification. |
+| "Just this once" | No exceptions — "just this once" is how standards die. |
+| "The last run passed" | Stale results. Run fresh verification now. |
+```
+
+### What Makes a Good Entry
+
+- **Excuse column**: Real phrases AI uses to justify skipping. Be specific.
+- **Reality column**: The direct counter. Short, imperative, no hedging.
+- Cover at least 4–6 common excuses for discipline skills.
+
+## Exit Criteria
+
+Every Technique or Discipline skill must end with a verifiable checklist the AI can check off before declaring the task done.
+
+```markdown
+## Exit Criteria
+
+Before claiming this task is complete:
+- [ ] [Verifiable condition 1]
+- [ ] [Verifiable condition 2]
+- [ ] [Verifiable condition 3]
+```
+
+**Rules for Exit Criteria:**
+- Each item must be binary (done or not done) — no vague "looks good" items
+- Must be something that can be checked programmatically or by inspection
+- Failing any item = task is NOT complete
+
+## Anti-Patterns to Avoid
+
+| ❌ Anti-Pattern | ✅ Fix |
+|----------------|-------|
+| Narrative prose everywhere | Tables, bullet lists, code blocks |
+| Discipline skill with no Anti-Rationalization | Add the table — it's mandatory |
+| Technique skill with no Exit Criteria | Add verifiable checklist |
+| Vague description | Specific triggers and use cases |
+| Generic labels ("Step 1", "Step 2") | Descriptive labels ("Verify baseline", "Run tests") |
+| Code examples in flowchart labels | Flowcharts for flow, code blocks for code |
+
+## Skill Creation Checklist
+
+- [ ] Description field triggers correctly (test: "would AI load this for X?")
+- [ ] Core principle stated in Overview
+- [ ] Content uses tables/code blocks, not prose paragraphs
+- [ ] Token-efficient (no redundant explanations)
+- [ ] **Anti-Rationalization section included** (Discipline/Technique skills — mandatory)
+- [ ] **Exit Criteria section included** (Discipline/Technique skills — mandatory)
+- [ ] Integration section lists related skills
+- [ ] Tested: create a scenario where this skill should fire, verify it does
+
+## Testing Skills
+
+For **discipline skills** (rules): Create scenario where rule should fire, verify AI follows it AND rejects the rationalizations in the Anti-Rationalization table.
+For **technique skills** (how-to): Apply skill to a real task, verify output quality and that Exit Criteria are met.
+For **reference skills** (docs): Query for specific info, verify correct answer.
+
+## The Bottom Line
+
+A skill is good when:
+1. It fires when it should (good description/CSO)
+2. It improves output quality noticeably
+3. It's token-efficient (doesn't waste context)
+4. It has no ambiguous loopholes (Anti-Rationalization table closes them)
+5. It's verifiable (Exit Criteria defines "done")