⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

tdd

shelpuk-ai-technology-consulting@shelpuk-ai-technology-consulting⭐ 32 stars· last commit 7mo ago· 0 open issues

Use for every coding task. Enforce strict TDD workflow: activate Serena, investigate first, clarify+confirm requirements, write per-task REQUIREMENTS.md in .requirements/<datetime>_<feature_name>/, verify APIs via web search, then implement in tiny test-verified steps.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 32 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Improve AI-generated code quality by 20%

TDD Skill is a part of the Shelpuk AI Technology Consulting agentic suite – a set of tools that together improve the code quality produced by AI coding agents by 15–20%. Read more on Claude Code generation quality improvement.

Works with Claude Code, Codex, Antigravity, Cursor, Windsurf, and any agent that supports skills or MCP servers.

ComponentRole
tdd ← you are hereEnforces TDD, requirements discipline, and peer review for every coding task
SerenaSemantic code navigation + persistent project memory
Kindly Web SearchUp-to-date API and package documentation via web search
Lad MCP ServerProject-aware AI design and code review

If you like what we're building, please ⭐ star this repo – it's a huge motivation for us to keep going!

How to use the suite

1. Install three MCP servers and one skill:

2. Use the skill when requesting a feature:

Prompt your favorite AI coding agent (Claude Code, Codex, Cursor, etc.) as usual. Then just add Follow $tdd in the end.

> Build [your feature description]. Follow $tdd.

TDD Skill

Why enforce TDD with a skill?

Picture this: Your AI coding agent just finished a new feature. The code looks clean, the agent is confident – but there's no record of what the feature was supposed to do, the edge cases were never discussed, and when you ask the agent about its design decisions next week, it has no idea what you're referring to. A month later you discover it silently broke an integration that was agreed on in a conversation the agent never saw.

This isn't a bug in the code. It's a bug in the process.

The "No Process" Problem

AI coding agents are stateless by default. Each session starts fresh. Without a structured workflow, even the best models routinely:

  • Jump straight to implementation without understanding requirements
  • Skip tests or write them after the fact as an afterthought
  • Make design decisions without checking current API documentation
  • Review their own code and miss "bad token" self-reinforcing mistakes
  • Lose all decisions and reasoning the moment the session ends

The result? Technically coherent code that solves the wrong problem – and no paper trail to figure out how you got there.

What This Skill Does Differently

We built this skill at Shelpuk AI Technology Consulting because we needed our AI coding agents to work the way disciplined engineers work: clarify before building, document before coding, test before shipping, and get a second opinion before merging.

✅ Investigate first, code second – agents understand the current state before proposing any changes

✅ Explicit requirements confirmation – no requirement changes without human sign-off, no silent interpretation

✅ Per-task requirements history – each task gets its own .requirements/<datetime>_<feature_name>/REQUIREMENTS.md with As Is / To Be / Requirements / Acceptance Criteria / Testing Plan / Implementation Plan; nothing is ever overwritten

✅ Validated assumptions – agents use Kindly Web Search to confirm API signatures, breaking changes, and deprecations before implementing

✅ Design review before code – architectural proposals go through Lad MCP Server system_design_review before a line is written

✅ Strict TDD in the smallest possible steps – tests first, implementation second, then Lad code_review on every change

✅ Project memory via Serena – design decisions, debug findings, and conventions are stored in Serena memories and survive across sessions and team members

If you find this useful, please drop us a star ⭐ – it's huge motivation for us to keep improving it!

How It Works

The tdd skill is a SKILL.md file that Codex and Claude Code discover automatically from ~/.codex/skills/tdd/ or ~/.claude/skills/tdd/. When active, it instructs the agent to follow a 6-step workflow for every coding task:

  1. Activate Serena – for semantic code navigation and persistent project memory
  2. Investigate – understand the current state before proposing any changes
  3. Clarify + confirm requirements – ask questions, propose concrete testable requirements, get explicit confirmation
  4. Write REQUIREMENTS.md – create .requirements/<YYYYMMDDTHHMMSSZ>_<feature_name>/REQUIREMENTS.md before any implementation begins
  5. Review design with Lad – run the requirements and system design through system_design_review, iterate until feedback runs dry
  6. Implement with TDD, reviewed by Lad – write tests first, implement, run tests, run code_review on each change, iterate

Skill Suite

This skill is part of a suite designed to work together:

ToolRole
SerenaSemantic code navigation + persistent project memory
Kindly Web SearchUp-to-date API/package documentation via web search
Lad MCP ServerProject-aware AI code and design review

Install

skill-installer (recommended for Codex)

Use skill-installer to pull directly from GitHub without copying or symlinking files manually. This uses the built-in Codex system skill (skill-installer) and its helper script.

Primary (recommended, branch-agnostic):

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo Shelpuk-AI-Technology-Consulting/agent-skill-tdd --path skills/tdd

Alternative (explicit branch/path URL):

$skill-installer install https://github.com/Shelpuk-AI-Technology-Consulting/agent-skill-tdd/tree/main/skills/tdd

(Replace main with another ref if needed.)

Troubleshooting: A bare repo URL (e.g. https://github.com/Shelpuk-AI-Technology-Consulting/agent-skill-tdd) fails with Missing --path for GitHub URL. Use one of the path-aware forms above.

Restart Codex after installing. Claude Code loads/updates skills automatically when they change.

Codex (manual)

Codex discovers skills from .codex/skills/ (repo-scoped) and ~/.codex/skills/ (user-scoped).

User-scoped (applies to all repos):

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/tdd" ~/.codex/skills/tdd
# or: cp -R skills/tdd ~/.codex/skills/tdd

Repo-scoped (applies to one target repo):

mkdir -p <target-repo>/.codex/skills
ln -s "$(pwd)/skills/tdd" <target-repo>/.codex/skills/tdd
# or: cp -R skills/tdd <target-repo>/.codex/skills/tdd

Restart Codex. Verify with /skills (or type $ to browse skills).

Troubleshooting: If Codex reports invalid YAML: mapping values are not allowed in this context, the frontmatter description contains : without quoting. Fix: description: "…workflow: activate…".

Claude Code (manual)

Claude Code discovers skills from .claude/skills/ (repo-scoped) and ~/.claude/skills/ (user-scoped).

User-scoped (applies to all repos):

mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/tdd" ~/.claude/skills/td

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/tdd/SKILL.md8.6 KB81e0be03db14upstream ↗
    ---
    name: tdd
    description: "Use for every coding task. Enforce strict TDD workflow: activate Serena, investigate first, clarify+confirm requirements, write per-task REQUIREMENTS.md in .requirements/<datetime>_<feature_name>/, verify APIs via web search, then implement in tiny test-verified steps."
    metadata:
      short-description: Always-on TDD workflow + requirements discipline.
    ---
    
    ## Working Agreement
    
    This skill is intentionally **always-on** for coding tasks. Follow it exactly unless the user explicitly opts out.
    
    ### Non-negotiables
    
    1. **Serena first**: Start by activating the Serena project (if the Serena tools exist in the environment). If activation fails for reasons outside your control, continue without Serena and say why.
    2. **Investigate before changing anything**: Understand the current state (application state, execution results, user input, logs) before proposing edits.
    3. **No requirement changes without confirmation**: If requirements are unclear, ask clarifying questions. Before you change/add/interpret requirements, get explicit confirmation.
    4. **Create a per-task `REQUIREMENTS.md` before implementation**:
       - Create/use root `.requirements/`.
       - For each task, choose a short snake_case feature name using lowercase ASCII letters, digits, and underscores only (for example, `update_github_authentication`).
       - Create a folder named `<datetime>_<feature_name>` using UTC datetime format `YYYYMMDDTHHMMSSZ` (for example, `20260301T143210Z_update_github_authentication`).
       - If the folder already exists, append a numeric suffix (`_01`, `_02`, and so on) to avoid collisions. Example: `.requirements/20260301T143210Z_update_github_authentication_01/`.
       - Write the task requirements file to `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` using the mandated structure (below).
    5. **Use up-to-date docs**: When you rely on an API/package/technology detail, use Kindly Web Search (if available) to confirm signatures, version behavior, breaking changes, and deprecations.
    6. **Smallest possible steps (TDD)**: Implement one small change at a time and test each change (unit → integration → smoke as appropriate) before proceeding.
    
    ## Per-task `REQUIREMENTS.md` Structure (Mandated)
    
    For each task, write `REQUIREMENTS.md` to `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` with:
    
    1. **As Is**: current behavior/state (what exists today).
    2. **To Be**: desired behavior/state after the change.
    3. **Requirements**: functional requirements (numbered).
    4. **Acceptance Criteria**: for every functional requirement, add explicit acceptance criteria.
    5. **Testing Plan**: test strategy + cases (TDD best practices).
    6. **Implementation Plan**: the smallest sequential code changes; for each change, include how you’ll test it.
    
    ## Workflow (Step-by-step)
    
    ### 1) Investigate
    
    - Inspect the repository structure, relevant code paths, current behavior, and existing tests.
    - Run the smallest commands needed to confirm the current state (build/test, smoke, reproducer), when applicable.
    - Summarize findings briefly.
    
    ### 2) Clarify + confirm requirements
    
    - Ask clarifying questions where anything is ambiguous (scope, UX, edge cases, compatibility, performance).
    - Propose the requirements in concrete, testable language.
    - Ask for explicit confirmation before finalizing requirements or changing them.
    
    ### 3) Create task requirements folder + `REQUIREMENTS.md`
    
    - Ensure `.requirements/` exists at repository root.
    - Choose a concise snake_case `<feature_name>` (lowercase ASCII letters, digits, and underscores only).
    - Generate UTC `<datetime>` in format `YYYYMMDDTHHMMSSZ`.
    - Create `.requirements/<datetime>_<feature_name>/`.
    - If that folder already exists, append `_01`, `_02`, and so on, until you get a unique folder name.
    - Write `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` before implementation.
    - First, write the "As Is" section explaining the current state of the system. 
    - Then, write the "To Be" section, describing in detail how the system should behave after the necessary changes. 
    - Then write the "Requirements" section describing functional requirements.
    - Use Kindly Web Search to get up-to-date documentation and information on packages, functions, APIs, and other technologies you plan to use.
    - Record useful Kindly Web Search findings to Serena memories for future use.
    - Then go over the "Requirements" section once again, and for every functional requirement, you add acceptance criteria.
    - Then you add the "Testing Plan" section. You list there the testing plan for this new feature, following the test-driven development (TDD) best practices.
    - Write the "Implementation Plan" section. The Implementation Plan describes the feature implementation order and attributes every feature to the tests from the Testing Plan that should validate it. Now, this is super important! In the "Implementation Plan", you always describe the smallest possible changes that need to be implemented one after the other to implement the requirements. For every change, you describe how to test it.
    
    ### 4) Validate assumptions
    
    - Use Kindly Web Search to verify any API or dependency assumptions.
    - Update the current task's `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` if assumptions change (and re-confirm requirements when needed).
    
    ### 5) Review with Lad MCP
    
    - Review your system design in the current task's requirements file with `system_design_review` tool of the Lad MCP Server. Explain the requirements. Provide as much context as you can. 
    - Review Lad's feedback and consider whether it is worth taking into account. Then, if necessary, update the current task's requirements file to incorporate this feedback.
    - Keep reviewing the current task's requirements file with Lad until it stops providing useful feedback.
    
    ### 6) Implement with TDD and review with Lad
    
    - Follow the Implementation Plan in order.
    - Follow Test-Driven Development (TDD) best practices. Implement tests first. Implement feature next. Make sure the tests pass.
    - After each test is implemented, review the test implementation with Lad MCP Server `code_review` tool. Implement the suggestions that are worthy of consideration.
    - After each step: run the smallest relevant tests first; expand to broader tests when confidence is needed.
    - Keep diffs minimal and focused; avoid unrelated refactors.
    - Use Lad MCP Server `code_review` tool to review each of your code changes. Implement the suggestions that are worthy of consideration.
    - Keep reviewing your code with Lad until it stops providing useful feedback.
    - Record useful implementation comments and design information to Serena memories for future use.
    
    ## Workflow Activity Diagram (PlantUML)
    
    This diagram explains the same workflow as above in PlantUML format.
    
    ```plantuml
    @startuml
    start
    
    :Activate Serena project;
    if (Serena activation succeeds?) then (yes)
      :Proceed with Serena-enabled workflow;
    else (no)
      :Continue without Serena;
      :State why activation failed;
    endif
    
    :Investigate repository structure and current behavior;
    
    repeat
      :Clarify scope and requirements;
      :Ask questions when requirements are unclear;
      :Propose concrete, testable requirements;
    repeat while (Requirements confirmed?) is (no)
    
    :Ensure .requirements/ exists;
    :Choose <feature_name> and UTC <datetime>;
    :Create .requirements/<datetime>_<feature_name>/;
    if (Task folder exists?) then (yes)
      :Append _01, _02, ... until unique;
    endif
    :Write REQUIREMENTS.md (As Is/To Be/Requirements/AC/Testing/Plan);
    :Use Kindly Web Search for API/dependency assumptions;
    :Record useful web findings to Serena memory;
    
    while (Assumptions changed?) is (yes)
      :Update current task REQUIREMENTS.md;
      :Re-confirm requirements if needed;
      :Re-check assumptions with web search;
    endwhile (no)
    
    repeat
      :Run Lad system_design_review on requirements;
      :Apply useful requirements feedback;
    repeat while (More useful design feedback?) is (yes)
    
    repeat
      :Pick next smallest implementation step;
      :Write or update tests first;
      :Review test implementation with Lad code_review;
      :Apply worthwhile test feedback;
      :Implement code change;
      :Run smallest relevant tests;
      :Review code change with Lad code_review;
      :Apply worthwhile code feedback;
    repeat while (Implementation plan remaining?) is (yes)
    
    :Record useful implementation notes to Serena memory;
    stop
    @enduml
    ```
    
    ## Serena memories (when supported)
    
    When Serena memory tools are available, store important information as short memories:
    
    - `project_overview.md`: what the repo is, key architectural facts.
    - `suggested_commands.md`: build/test/lint/smoke commands.
    - `style_and_conventions.md`: coding conventions, patterns, gotchas.
    - `bugs.md`: notable bugs + fixes (date, cause, prevention) when applicable.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/shelpuk-ai-technology-consulting-agent-skill-tdd-skills-tdd.md

// REPO STATS

32 stars
0 open issues
Last commit: 7mo ago