tdd-guide

I've been digging through skill implementations and noticed your TDD guide takes a pretty opinionated stance on test structure—curious what made you prioritize that particular organization over the more common pyramid approach?

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 67/100, solidly in D territory. This is based on Anthropic's Progressive Disclosure Architecture standards and the 5-pillar rubric used across skill evaluation. Your Utility section is strong (15/20)—the actual problem-solving power is there. But Writing Style (4/10) and PDA structure (15/30) are dragging you down hard. Fix those two pillars and you're looking at a solid B.

What's Working Well

• Real utility: You're addressing actual TDD gaps (coverage analysis, test generation, multi-framework support). This isn't theoretical stuff.
• Good trigger terms: @tdd-guide, "run tdd guide" are clear discovery hooks.
• Framework flexibility: Supporting Jest, Pytest, JUnit, Vitest shows you understand developers work in different ecosystems.
• Structured sections: Your Best Practices section with numbered steps shows you understand workflow clarity.

The Big One: 288 Lines in a Single File (No References Directory)

This is your biggest blocker. Right now everything lives in one SKILL.md file—no layered structure, no references directory. This violates PDA (Progressive Disclosure Architecture) and kills your token efficiency score.

Why it matters: Skills over ~100 lines need to split content into separate files. Scripts, examples, detailed framework configs, and workflows should live in references/ subdirectory. This lets users pull in only what they need instead of parsing the whole thing.

The fix: Create this structure:

tdd-guide/
├── SKILL.md (trim to ~120 lines, add TOC)
├── references/
│   ├── scripts.md (test_generator.py, coverage_analyzer.py details)
│   ├── examples.md (concrete input/output pairs, before/after)
│   └── frameworks.md (Jest/Pytest/JUnit specific details)
└── README.md

Move your "Scripts" section details to references/scripts.md, all the capabilities descriptions to references/frameworks.md, and concrete examples to references/examples.md. Reference them from SKILL.md with inline links.

Point improvement: +10 points directly to PDA.

Other Things Worth Fixing

1. Add trigger phrases to frontmatter (currently missing). Your description should include: Use when asked to "tdd guide", "write tests with tdd", or "test-driven development workflow". Right now it's pure marketing fluff. +2 points

2. Cut the marketing language. Terms like "comprehensive", "intelligent", "smart defaults", "context-aware" are promotional, not instructional. Replace "Comprehensive Test Driven Development guide" with "Test Driven Development guide with test generation, coverage analysis, and framework integration." +4 points

3. Add TOC to SKILL.md. At 288 lines without a table of contents, users can't navigate. Add after frontmatter:

   ## Contents
   - [Capabilities](#capabilities)
   - [Input Requirements](#input-requirements)
   - [Output Formats](#output-formats)
   - [Best Practices](#best-practices)
   

   +3 points

4. Standardize voice and tense. You're mixing imperative ("Generate Test Cases"), infinitive ("Write tests"), and second-person ("you need"). Pick imperative throughout: "Generate test cases", "Write tests from user stories", "Configure test runners." +2 points

Quick Wins

• Move to ~19 points on PDA by creating references/ directory structure (+10)
• Fix Writing Style to ~8 by removing marketing language and standardizing voice (+4)
• Hit 80/100 by adding trigger phrases (+2) and TOC (+3)
• Most impactful: the references/ refactor alone gets you 10 points closer to a solid B

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.