@simplysm/sd-claude 13.0.78 → 13.0.80

package/claude/skills/sd-skill/SKILL.md

@@ -1,417 +0,0 @@
----
-name: sd-skill
-description: "Skill creation and editing (explicit invocation only)"
----
-
-# Writing Skills
-
-## Overview
-
-**Writing skills IS Test-Driven Development applied to process documentation.**
-
-You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
-
-**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
-
-**REQUIRED BACKGROUND:** You MUST understand sd-tdd before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
-
-**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
-
-## What is a Skill?
-
-A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
-
-**Skills are:** Reusable techniques, patterns, tools, reference guides
-
-**Skills are NOT:** Narratives about how you solved a problem once
-
-## TDD Mapping for Skills
-
-| TDD Concept             | Skill Creation                                   |
-| ----------------------- | ------------------------------------------------ |
-| **Test case**           | Pressure scenario with subagent                  |
-| **Production code**     | Skill document (SKILL.md)                        |
-| **Test fails (RED)**    | Agent violates rule without skill (baseline)     |
-| **Test passes (GREEN)** | Agent complies with skill present                |
-| **Refactor**            | Close loopholes while maintaining compliance     |
-| **Write test first**    | Run baseline scenario BEFORE writing skill       |
-| **Watch it fail**       | Document exact rationalizations agent uses       |
-| **Minimal code**        | Write skill addressing those specific violations |
-| **Watch it pass**       | Verify agent now complies                        |
-| **Refactor cycle**      | Find new rationalizations → plug → re-verify     |
-
-The entire skill creation process follows RED-GREEN-REFACTOR.
-
-## When to Create a Skill
-
-**Create when:**
-
-- Technique wasn't intuitively obvious to you
-- You'd reference this again across projects
-- Pattern applies broadly (not project-specific)
-- Others would benefit
-
-**Don't create for:**
-
-- 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)
-
-## Skill Types
-
-### Technique
-
-Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
-
-### Pattern
-
-Way of thinking about problems (flatten-with-flags, test-invariants)
-
-### Reference
-
-API docs, syntax guides, tool documentation (office docs)
-
-## Directory Structure
-
-```
-skills/
-  skill-name/
-    SKILL.md              # Main reference (required)
-    supporting-file.*     # Only if needed
-```
-
-**Flat namespace** - all skills in one searchable namespace
-
-**Separate files for:**
-
-1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
-2. **Reusable tools** - Scripts, utilities, templates
-
-**Keep inline:**
-
-- Principles and concepts
-- Code patterns (< 50 lines)
-- Everything else
-
-## SKILL.md Structure
-
-**Frontmatter (YAML):**
-
-- 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-guide.md for why)
-  - Keep under 500 characters if possible
-
-```markdown
----
-name: Skill-Name-With-Hyphens
-description: Use when [specific triggering conditions and symptoms]
----
-
-# Skill Name
-
-## Overview
-
-What is this? Core principle in 1-2 sentences.
-
-## When to Use
-
-[Small inline flowchart IF decision non-obvious]
-
-Bullet list with SYMPTOMS and use cases
-When NOT to use
-
-## Core Pattern (for techniques/patterns)
-
-Before/after code comparison
-
-## Quick Reference
-
-Table or bullets for scanning common operations
-
-## Implementation
-
-Inline code for simple patterns
-Link to file for heavy reference or reusable tools
-
-## Common Mistakes
-
-What goes wrong + fixes
-
-## Real-World Impact (optional)
-
-Concrete results
-```
-
-## Claude Search Optimization (CSO)
-
-**Critical for discovery.** See **cso-guide.md** for the complete guide covering description fields, keyword coverage, naming, token efficiency, and cross-referencing.
-
-## Writing Guidelines
-
-**See writing-guide.md** for flowchart usage, code examples, file organization, and bulletproofing techniques.
-
-## The Iron Law (Same as TDD)
-
-```
-NO SKILL WITHOUT A FAILING TEST FIRST
-```
-
-This applies to NEW skills AND EDITS to existing skills.
-
-Write skill before testing? Delete it. Start over.
-Edit skill without testing? Same violation.
-
-**No exceptions:**
-
-- 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
-
-**Only exemption — pure mechanical edits:** Typo fixes, tool/variable renames where the behavioral guidance is identical (e.g., `TodoWrite` → `TaskCreate`). If you're changing what the skill *teaches*, it's not mechanical — test it.
-
-**REQUIRED BACKGROUND:** The sd-tdd skill explains why this matters. Same principles apply to documentation.
-
-## Testing All Skill Types
-
-Different skill types need different test approaches:
-
-```mermaid
-flowchart TD
-    A{"What type of skill?"}
-    A -->|"Discipline (rules/requirements)"| B["Pressure test<br>(compliance under stress)"]
-    A -->|"Technique (how-to guides)"| C["Application test<br>(correct technique usage)"]
-    A -->|"Pattern (mental models)"| D["Recognition test<br>(when/how to apply)"]
-    A -->|"Reference (docs/APIs)"| E["Retrieval test<br>(find & use reference)"]
-```
-
-### 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?
-
-**How to test:** Give a subagent a problem the technique solves, WITHOUT the skill. Observe what approach they use naturally. Then give the SAME problem WITH the skill and verify they apply the technique correctly.
-
-```
-Example: Testing a "condition-based-waiting" skill
-1. Ask subagent: "Fix this flaky test that uses setTimeout(500)"
-2. WITHOUT skill: Agent increases timeout to 2000ms (wrong approach)
-3. WITH skill: Agent replaces with polling/condition check (correct)
-```
-
-**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
-
-## Common Rationalizations for Skipping Testing
-
-| Excuse                                 | Reality                                                                                                         |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| "Skill is obviously clear"             | Clear to you ≠ clear to other agents. Test it.                                                                  |
-| "It's just a reference"                | References can have gaps, unclear sections. Test retrieval.                                                     |
-| "Testing is overkill"                  | Untested skills have issues. Always. 15 min testing saves hours.                                                |
-| "I'll test if problems emerge"         | Problems = agents can't use skill. Test BEFORE deploying.                                                       |
-| "Too tedious to test"                  | Testing is less tedious than debugging bad skill in production.                                                 |
-| "I'm confident it's good"              | Overconfidence guarantees issues. Test anyway.                                                                  |
-| "Academic review is enough"            | Reading ≠ using. Test application scenarios.                                                                    |
-| "No time to test"                      | Deploying untested skill wastes more time fixing it later.                                                      |
-| "I already know the baseline failures" | You know what YOU think the failures are. Run a subagent to see what ACTUALLY happens. Knowledge ≠ observation. |
-| "This is process theater" | If the process catches even one issue you missed, it paid for itself. "Theater" is what you call process before it saves you. |
-| "It applies the wrong test methodology" | Different skill types need different tests (pressure vs retrieval), but ALL types need testing. No type is exempt. |
-
-**All of these mean: Test before deploying. No exceptions.**
-
-## Bulletproofing Skills Against Rationalization
-
-Skills that enforce discipline need to resist rationalization. **See writing-guide.md** for detailed techniques on closing loopholes, spirit-vs-letter arguments, rationalization tables, and red flags lists.
-
-## RED-GREEN-REFACTOR for Skills
-
-Follow the TDD cycle:
-
-### Subagent Rules
-
-**NEVER use `isolation: "worktree"` when launching subagents.** Worktrees break lint/build tooling. Always run subagents in the default (non-isolated) mode.
-
-### RED: Write Failing Test (Baseline)
-
-Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
-
-- What choices did they make?
-- What rationalizations did they use (verbatim)?
-- Which pressures triggered violations?
-
-This is "watch the test fail" - you must see what agents naturally do before writing the skill.
-
-**You MUST actually run a subagent.** Do not substitute your own knowledge of "what agents would probably do." Your prediction of baseline behavior ≠ observed baseline behavior. Run the subagent, read the output, document what actually happened.
-
-### GREEN: Write Minimal Skill
-
-Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.
-
-Run same scenarios WITH skill. Agent should now comply.
-
-### REFACTOR: Close Loopholes
-
-Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
-
-**Testing methodology:** See testing-skills-with-subagents.md for the complete testing methodology:
-
-- How to write pressure scenarios
-- Pressure types (time, sunk cost, authority, exhaustion)
-- Plugging holes systematically
-- Meta-testing techniques
-
-## Anti-Patterns
-
-### ❌ Narrative Example
-
-"In session 2025-10-03, we found empty projectDir caused..."
-**Why bad:** Too specific, not reusable
-
-### ❌ Multi-Language Dilution
-
-example-js.js, example-py.py, example-go.go
-**Why bad:** Mediocre quality, maintenance burden
-
-### ❌ Code in Flowcharts
-
-```mermaid
-flowchart TD
-    A["import fs"] --> B["read file"]
-```
-
-**Why bad:** Can't copy-paste, hard to read
-
-### ❌ Generic Labels
-
-helper1, helper2, step3, pattern4
-**Why bad:** Labels should have semantic meaning
-
-## STOP: Before Moving to Next Skill
-
-**After writing ANY skill, you MUST STOP and complete the deployment process.**
-
-**Do NOT:**
-
-- Create multiple skills in batch without testing each
-- Move to next skill before current one is verified
-- Skip testing because "batching is more efficient"
-
-**The deployment checklist below is MANDATORY for EACH skill.**
-
-Deploying untested skills = deploying untested code. It's a violation of quality standards.
-
-## Skill Creation Checklist (TDD Adapted)
-
-**IMPORTANT: Use TaskCreate to create todos for EACH checklist item below.**
-
-**RED Phase - Write Failing Test:**
-
-- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
-- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
-- [ ] Identify patterns in rationalizations/failures
-
-**GREEN Phase - Write Minimal Skill:**
-
-- [ ] 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
-
-**REFACTOR Phase - Close Loopholes:**
-
-- [ ] 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
-
-**Quality Checks:**
-
-- [ ] Small flowchart only if decision non-obvious
-- [ ] Quick reference table
-- [ ] Common mistakes section
-- [ ] No narrative storytelling
-- [ ] Supporting files only for tools or heavy reference
-
-**Deployment:**
-
-- [ ] Commit skill to git and push to your fork (if configured)
-- [ ] Consider contributing back via PR (if broadly useful)
-
-## Discovery Workflow
-
-How future Claude finds your skill:
-
-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)
-
-**Optimize for this flow** - put searchable terms early and often.
-
-## The Bottom Line
-
-**Creating skills IS TDD for process documentation.**
-
-Same Iron Law: No skill without failing test first.
-Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
-Same benefits: Better quality, fewer surprises, bulletproof results.
-
-If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.

package/claude/skills/sd-skill/anthropic-best-practices.md

@@ -1,156 +0,0 @@
-# Skill Authoring Best Practices (Anthropic Official)
-
-> Condensed from Anthropic's official skill authoring guide. Covers patterns not already in cso-guide.md, writing-guide.md, or testing-skills-with-subagents.md.
-
-## Core Principles
-
-### Concise is key
-
-Context window is a public good. Only metadata (name, description) is pre-loaded; SKILL.md is read on-demand. But once loaded, every token competes with conversation history.
-
-**Default assumption:** Claude is already very smart. Only add context Claude doesn't already have.
-
-### Set appropriate degrees of freedom
-
-Match specificity to task fragility:
-
-| Freedom level | When to use | Example |
-|--------------|-------------|---------|
-| **High** (text instructions) | Multiple valid approaches, context-dependent | Code review process |
-| **Medium** (pseudocode/templates) | Preferred pattern exists, some variation ok | Report generation template |
-| **Low** (exact scripts) | Fragile operations, consistency critical | Database migration commands |
-
-**Analogy:** Narrow bridge with cliffs = low freedom (exact instructions). Open field = high freedom (general direction).
-
-### Test with all models you plan to use
-
-- **Haiku**: Does the Skill provide enough guidance?
-- **Sonnet**: Is the Skill clear and efficient?
-- **Opus**: Does the Skill avoid over-explaining?
-
-What works for Opus might need more detail for Haiku.
-
-## Skill Structure
-
-### Progressive disclosure
-
-SKILL.md = overview that points to detailed files. Keep body under 500 lines.
-
-```
-pdf/
-├── SKILL.md              # Main instructions (loaded when triggered)
-├── FORMS.md              # Form-filling guide (loaded as needed)
-├── reference.md          # API reference (loaded as needed)
-└── scripts/
-    ├── analyze_form.py   # Utility script (executed, not loaded)
-    └── fill_form.py      # Form filling script
-```
-
-**Key rules:**
-- Keep references one level deep from SKILL.md (no nested references)
-- For files 100+ lines, include table of contents at top
-- Name files descriptively: `form_validation_rules.md`, not `doc2.md`
-
-## Workflows and Feedback Loops
-
-### Use workflows for complex tasks
-
-Break complex operations into sequential steps with a checklist:
-
-````markdown
-## PDF form filling workflow
-
-```
-Task Progress:
-- [ ] Step 1: Analyze the form (run analyze_form.py)
-- [ ] Step 2: Create field mapping (edit fields.json)
-- [ ] Step 3: Validate mapping (run validate_fields.py)
-- [ ] Step 4: Fill the form (run fill_form.py)
-- [ ] Step 5: Verify output (run verify_output.py)
-```
-````
-
-### Implement feedback loops
-
-**Pattern:** Run validator -> fix errors -> repeat
-
-```markdown
-1. Make edits to document
-2. **Validate immediately**: `python scripts/validate.py`
-3. If validation fails: fix issues, run validation again
-4. **Only proceed when validation passes**
-```
-
-### Conditional workflow pattern
-
-```markdown
-1. Determine the modification type:
-   **Creating new?** -> Follow "Creation workflow"
-   **Editing existing?** -> Follow "Editing workflow"
-```
-
-## Content Guidelines
-
-- **Avoid time-sensitive info**: Use "Current method" / "Old patterns" sections instead of dates
-- **Consistent terminology**: Pick one term and use it throughout (not "endpoint" + "URL" + "route")
-- **Provide defaults, not options**: "Use pdfplumber" not "You can use pypdf, or pdfplumber, or..."
-
-## Executable Code Patterns
-
-### Solve, don't punt
-
-Handle errors in scripts rather than failing and letting Claude figure it out.
-
-### Plan-validate-execute pattern
-
-For complex batch operations, add an intermediate plan file:
-
-1. Analyze input
-2. **Create plan file** (e.g., `changes.json`)
-3. **Validate plan** with script
-4. Execute plan
-5. Verify output
-
-Catches errors before changes are applied. Use for: batch operations, destructive changes, high-stakes operations.
-
-### Utility scripts
-
-Pre-made scripts > generated code:
-- More reliable, save tokens, ensure consistency
-- Make execution intent clear: "Run `script.py`" (execute) vs "See `script.py`" (read as reference)
-
-### Package dependencies
-
-List required packages in SKILL.md and verify availability.
-
-### MCP tool references
-
-Always use fully qualified names: `ServerName:tool_name`
-
-```markdown
-Use the BigQuery:bigquery_schema tool to retrieve table schemas.
-```
-
-## Checklist
-
-### Core quality
-- [ ] Description specific with key terms
-- [ ] SKILL.md body under 500 lines
-- [ ] No time-sensitive information
-- [ ] Consistent terminology
-- [ ] Concrete examples
-- [ ] References one level deep
-- [ ] Clear workflow steps
-
-### Code and scripts
-- [ ] Scripts solve problems (don't punt to Claude)
-- [ ] Explicit error handling
-- [ ] No magic constants
-- [ ] Required packages listed
-- [ ] Forward slashes in paths (not backslash)
-- [ ] Validation/verification steps for critical operations
-- [ ] Feedback loops for quality-critical tasks
-
-### Testing
-- [ ] Tested with real usage scenarios
-- [ ] Tested across model tiers if applicable