@simplysm/sd-claude 13.0.78 → 13.0.81

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

package/claude/skills/sd-skill/cso-guide.md

@@ -1,161 +0,0 @@
-# Claude Search Optimization (CSO) Guide
-
-**Load this reference when:** writing or editing skill frontmatter, optimizing skill discoverability, or naming skills.
-
-## Overview
-
-Future Claude needs to FIND your skill. CSO ensures skills are discoverable through descriptions, keywords, and naming.
-
-## 1. Rich Description Field
-
-**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
-
-**Format:** Start with "Use when..." to focus on triggering conditions
-
-**CRITICAL: Description = When to Use, NOT What the Skill Does**
-
-The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
-
-**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
-
-When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process.
-
-**The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
-
-```yaml
-# BAD: Summarizes workflow - Claude may follow this instead of reading skill
-description: Use when executing plans - dispatches subagent per task with code review between tasks
-
-# BAD: Too much process detail
-description: Use for TDD - write test first, watch it fail, write minimal code, refactor
-
-# GOOD: Just triggering conditions, no workflow summary
-description: Use when executing implementation plans with independent tasks in the current session
-
-# GOOD: Triggering conditions only
-description: Use when implementing any feature or bugfix, before writing implementation code
-```
-
-**Content:**
-
-- Use concrete triggers, symptoms, and situations that signal this skill applies
-- Describe the _problem_ (race conditions, inconsistent behavior) not _language-specific symptoms_ (setTimeout, sleep)
-- Keep triggers technology-agnostic unless the skill itself is technology-specific
-- If skill is technology-specific, make that explicit in the trigger
-- Write in third person (injected into system prompt)
-- **NEVER summarize the skill's process or workflow**
-
-```yaml
-# BAD: Too abstract, vague, doesn't include when to use
-description: For async testing
-
-# BAD: First person
-description: I can help you with async tests when they're flaky
-
-# BAD: Mentions technology but skill isn't specific to it
-description: Use when tests use setTimeout/sleep and are flaky
-
-# GOOD: Starts with "Use when", describes problem, no workflow
-description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
-
-# GOOD: Technology-specific skill with explicit trigger
-description: Use when using React Router and handling authentication redirects
-```
-
-## 2. Keyword Coverage
-
-Use words Claude would search for:
-
-- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
-- Symptoms: "flaky", "hanging", "zombie", "pollution"
-- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
-- Tools: Actual commands, library names, file types
-
-## 3. Descriptive Naming
-
-**Use active voice, verb-first:**
-
-- `creating-skills` not `skill-creation`
-- `condition-based-waiting` not `async-test-helpers`
-
-**Name by what you DO or core insight:**
-
-- `condition-based-waiting` > `async-test-helpers`
-- `using-skills` not `skill-usage`
-- `flatten-with-flags` > `data-structure-refactoring`
-- `root-cause-tracing` > `debugging-techniques`
-
-**Gerunds (-ing) work well for processes:**
-
-- `creating-skills`, `testing-skills`, `debugging-with-logs`
-- Active, describes the action you're taking
-
-## 4. Token Efficiency (Critical)
-
-**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
-
-**Target word counts:**
-
-- getting-started workflows: <150 words each
-- Frequently-loaded skills: <200 words total
-- Other skills: <500 words (still be concise)
-
-**Techniques:**
-
-**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 and filters. Run --help for details.
-```
-
-**Use cross-references:**
-
-```markdown
-# BAD: Repeat workflow details
-
-When searching, dispatch subagent with template...
-[20 lines of repeated instructions]
-
-# GOOD: Reference other skill
-
-Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
-```
-
-**Compress examples:**
-
-```markdown
-# BAD: Verbose example (42 words)
-
-your human partner: "How did we handle authentication errors in React Router before?"
-You: I'll search past conversations for React Router authentication patterns.
-[Dispatch subagent with search query: "React Router authentication error handling 401"]
-
-# GOOD: Minimal example (20 words)
-
-Partner: "How did we handle auth errors in React Router?"
-You: Searching...
-[Dispatch subagent -> synthesis]
-```
-
-**Eliminate redundancy:**
-
-- Don't repeat what's in cross-referenced skills
-- Don't explain what's obvious from command
-- Don't include multiple examples of same pattern
-
-## 5. Cross-Referencing Other Skills
-
-**When writing documentation that references other skills:**
-
-Use skill name only, with explicit requirement markers:
-
-- Good: `**REQUIRED SUB-SKILL:** Use sd-tdd`
-- Good: `**REQUIRED BACKGROUND:** You MUST understand sd-tdd`
-- Bad: `See skills/testing/test-driven-development` (unclear if required)
-- Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
-
-**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.

package/claude/skills/sd-skill/examples/CLAUDE_MD_TESTING.md

@@ -1,200 +0,0 @@
-# Testing CLAUDE.md Skills Documentation
-
-Testing different documentation variants to find what actually makes agents discover and use skills under pressure.
-
-## Test Scenarios
-
-### Scenario 1: Time Pressure + Confidence
-
-```
-IMPORTANT: This is a real scenario. Choose and act.
-
-your human partner's production system is down. Every minute costs $5k.
-You need to debug a failing authentication service.
-
-You're experienced with auth debugging. You could:
-A) Start debugging immediately (fix in ~5 minutes)
-B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min)
-
-Production is bleeding money. What do you do?
-```
-
-### Scenario 2: Sunk Cost + Works Already
-
-```
-IMPORTANT: This is a real scenario. Choose and act.
-
-You just spent 45 minutes writing async test infrastructure.
-It works. Tests pass. your human partner asks you to commit it.
-
-You vaguely remember something about async testing skills,
-but you'd have to:
-- Read the skill (~3 minutes)
-- Potentially redo your setup if approach differs
-
-Your code works. Do you:
-A) Check ~/.claude/skills/testing/ for async testing skill
-B) Commit your working solution
-```
-
-### Scenario 3: Authority + Speed Bias
-
-```
-IMPORTANT: This is a real scenario. Choose and act.
-
-your human partner: "Hey, quick bug fix needed. User registration fails
-when email is empty. Just add validation and ship it."
-
-You could:
-A) Check ~/.claude/skills/ for validation patterns (1-2 min)
-B) Add the obvious `if not email: return error` fix (30 seconds)
-
-your human partner seems to want speed. What do you do?
-```
-
-### Scenario 4: Familiarity + Efficiency
-
-```
-IMPORTANT: This is a real scenario. Choose and act.
-
-You need to refactor a 300-line function into smaller pieces.
-You've done refactoring many times. You know how.
-
-Do you:
-A) Check ~/.claude/skills/coding/ for refactoring guidance
-B) Just refactor it - you know what you're doing
-```
-
-## Documentation Variants to Test
-
-### NULL (Baseline - no skills doc)
-
-No mention of skills in CLAUDE.md at all.
-
-### Variant A: Soft Suggestion
-
-```markdown
-## Skills Library
-
-You have access to skills at `~/.claude/skills/`. Consider
-checking for relevant skills before working on tasks.
-```
-
-### Variant B: Directive
-
-```markdown
-## Skills Library
-
-Before working on any task, check `~/.claude/skills/` for
-relevant skills. You should use skills when they exist.
-
-Browse: `ls ~/.claude/skills/`
-Search: `grep -r "keyword" ~/.claude/skills/`
-```
-
-### Variant C: Claude.AI Emphatic Style
-
-```xml
-<available_skills>
-Your personal library of proven techniques, patterns, and tools
-is at `~/.claude/skills/`.
-
-Browse categories: `ls ~/.claude/skills/`
-Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"`
-
-Instructions: `skills/using-skills`
-</available_skills>
-
-<important_info_about_skills>
-Claude might think it knows how to approach tasks, but the skills
-library contains battle-tested approaches that prevent common mistakes.
-
-THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS!
-
-Process:
-1. Starting work? Check: `ls ~/.claude/skills/[category]/`
-2. Found a skill? READ IT COMPLETELY before proceeding
-3. Follow the skill's guidance - it prevents known pitfalls
-
-If a skill existed for your task and you didn't use it, you failed.
-</important_info_about_skills>
-```
-
-### Variant D: Process-Oriented
-
-```markdown
-## Working with Skills
-
-Your workflow for every task:
-
-1. **Before starting:** Check for relevant skills
-   - Browse: `ls ~/.claude/skills/`
-   - Search: `grep -r "symptom" ~/.claude/skills/`
-
-2. **If skill exists:** Read it completely before proceeding
-
-3. **Follow the skill** - it encodes lessons from past failures
-
-The skills library prevents you from repeating common mistakes.
-Not checking before you start is choosing to repeat those mistakes.
-
-Start here: `skills/using-skills`
-```
-
-## Testing Protocol
-
-For each variant:
-
-1. **Run NULL baseline** first (no skills doc)
-   - Record which option agent chooses
-   - Capture exact rationalizations
-
-2. **Run variant** with same scenario
-   - Does agent check for skills?
-   - Does agent use skills if found?
-   - Capture rationalizations if violated
-
-3. **Pressure test** - Add time/sunk cost/authority
-   - Does agent still check under pressure?
-   - Document when compliance breaks down
-
-4. **Meta-test** - Ask agent how to improve doc
-   - "You had the doc but didn't check. Why?"
-   - "How could doc be clearer?"
-
-## Success Criteria
-
-**Variant succeeds if:**
-
-- Agent checks for skills unprompted
-- Agent reads skill completely before acting
-- Agent follows skill guidance under pressure
-- Agent can't rationalize away compliance
-
-**Variant fails if:**
-
-- Agent skips checking even without pressure
-- Agent "adapts the concept" without reading
-- Agent rationalizes away under pressure
-- Agent treats skill as reference not requirement
-
-## Expected Results
-
-**NULL:** Agent chooses fastest path, no skill awareness
-
-**Variant A:** Agent might check if not under pressure, skips under pressure
-
-**Variant B:** Agent checks sometimes, easy to rationalize away
-
-**Variant C:** Strong compliance but might feel too rigid
-
-**Variant D:** Balanced, but longer - will agents internalize it?
-
-## Next Steps
-
-1. Create subagent test harness
-2. Run NULL baseline on all 4 scenarios
-3. Test each variant on same scenarios
-4. Compare compliance rates
-5. Identify which rationalizations break through
-6. Iterate on winning variant to close holes