How the Test-Driven Development Skill Implements the Red-Green-Refactor Cycle

The test-driven development skill encodes the Red-Green-Refactor workflow as explicit, documented steps in skills/test-driven-development/SKILL.md, directing AI agents to write failing tests first, implement minimal passing code, and continuously refactor while maintaining green test status.

The test-driven development skill in the addyosmani/agent-skills repository provides a structured framework for AI agents to follow disciplined TDD principles. This skill translates the classic Red-Green-Refactor cycle into concrete, executable instructions that ensure every code change is verified by automated tests. By embedding this methodology directly into the agent's operational context, the repository enables systematic, regression-resistant software development.

Step-by-Step Implementation of the Red-Green-Refactor Cycle

The skill defines the TDD workflow as three distinct, sequential phases that the AI agent must execute when adding or modifying functionality.

Step 1: Red – Write a Failing Test

According to the source code in skills/test-driven-development/SKILL.md, the RED phase requires the agent to create a test that deliberately fails because the target implementation does not yet exist. This failing test serves as an unambiguous specification of the desired behavior, establishing a concrete goal for the implementation phase.

The skill instructs the agent to define the test with precise expectations before writing any production code. For example, when implementing a new task creation feature, the agent would write:

describe('TaskService', () => {
  it('creates a task with title and default status', async () => {
    const task = await taskService.createTask({ title: 'Buy groceries' });

    expect(task.id).toBeDefined();
    expect(task.title).toBe('Buy groceries');
    expect(task.status).toBe('pending');
    expect(task.createdAt).toBeInstanceOf(Date);
  });
});

Step 2: Green – Make the Test Pass

Once the test fails as expected, the skill directs the agent to the GREEN phase, where the goal is to write the smallest possible implementation that satisfies the test. The instructions explicitly prohibit adding extra logic, abstractions, or optimizations at this stage.

As implemented in the SKILL.md file, the agent produces minimal working code such as:

export async function createTask(input: { title: string }): Promise<Task> {
  const task = {
    id: generateId(),
    title: input.title,
    status: 'pending' as const,
    createdAt: new Date(),
  };
  await db.tasks.insert(task);
  return task;
}

This implementation provides exactly enough functionality to make the previously failing test pass, satisfying the green requirement without over-engineering.

Step 3: Refactor – Clean Up While Staying Green

With tests now passing, the skill initiates the REFACTOR phase, where the agent improves code quality through renaming, extracting shared logic, removing duplication, and enhancing type safety. The critical constraint, as defined in SKILL.md, requires running the test suite after each refactoring change to guarantee behavior remains unchanged.

Typical refactoring actions include:

• Extracting generateId() into a dedicated utility module
• Replacing inline object construction with a TaskBuilder class when complexity increases
• Adding explicit TypeScript interfaces for Task and CreateTaskInput

Each refactoring step must be followed by executing npm test (or the configured test runner) to confirm the green state persists throughout the cleanup process.

The Prove-It Pattern for Bug Fixes

Beyond new feature development, the test-driven development skill embeds the Prove-It pattern for handling bug fixes. This pattern forces the agent to execute the same Red-Green-Refactor loop before applying any fix, ensuring regression protection through test coverage.

As documented in the "Prove-It Pattern" section of skills/test-driven-development/SKILL.md, the agent must first write a reproduction test that demonstrates the bug (RED), then apply the minimal fix to make the test pass (GREEN), and finally refactor if necessary. This approach guarantees that every bug fix is accompanied by a test that prevents future regressions.

File Structure and Integration

The TDD skill relies on several interconnected files within the addyosmani/agent-skills repository:

• skills/test-driven-development/SKILL.md – Contains the procedural logic defining the RED-GREEN-REFACTOR workflow, code examples, and the Prove-It pattern
• references/testing-patterns.md – Provides broader context on testing strategies that complement the TDD skill
• agents/test-engineer.md – Demonstrates how sub-agents may spawn to write reproduction tests before fixes, reinforcing the RED step
• hooks/session-start.sh – Initializes the agent environment, ensuring the TDD skill is available at session startup

Together, these files form a self-contained, repeatable workflow that AI agents can execute automatically according to the repository's OpenCode architecture.

Summary

• The test-driven development skill encodes the Red-Green-Refactor cycle in skills/test-driven-development/SKILL.md as explicit instructions for AI agents
• RED phase requires writing a deliberately failing test that specifies desired behavior before implementation exists
• GREEN phase demands the minimal implementation that satisfies the test, prohibiting premature abstraction or optimization
• REFACTOR phase allows code cleanup and improvement only while continuously verifying that tests remain green
• The Prove-It pattern extends TDD to bug fixes by requiring a reproduction test before any fix is applied
• Supporting files like agents/test-engineer.md and hooks/session-start.sh integrate the skill into the broader OpenCode workflow

Frequently Asked Questions

What is the Prove-It pattern in the test-driven development skill?

The Prove-It pattern is a TDD enforcement mechanism documented in skills/test-driven-development/SKILL.md that requires AI agents to write a failing reproduction test before fixing any bug. This ensures that every bug fix is verified by a test that prevents regression, effectively treating bug fixes as new features that must pass through the complete Red-Green-Refactor cycle.

How does the skill ensure minimal implementation during the Green phase?

The skill explicitly instructs agents to write only the code necessary to make the current test pass, prohibiting extra logic, abstractions, or optimizations. According to the "Step 2: GREEN" section in SKILL.md, the agent must resist the urge to build beyond the test's requirements, ensuring the implementation remains focused and verifiable.

Where is the test-driven development skill defined in the repository?

The primary definition resides in skills/test-driven-development/SKILL.md, which contains the complete Red-Green-Refactor workflow description, code examples, and the Prove-It pattern. Supporting context is available in references/testing-patterns.md, while agents/test-engineer.md demonstrates practical application of the skill through sub-agent utilization.

Can the TDD skill handle both TypeScript and other languages?

While the provided examples in SKILL.md use TypeScript syntax, the Red-Green-Refactor workflow itself is language-agnostic. The skill focuses on the procedural methodology—writing failing tests, minimal implementations, and refactoring—rather than specific language constraints, making it adaptable to any codebase that supports automated testing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}