Writing Skills

Test-driven development for creating and editing skills. Write test cases, watch them fail, write the skill, watch tests pass, and refactor to close loopholes.

Download this Skill

npx degit LangbaseInc/agent-skills/writing-skills my-writing-skills

TDD for Skills

Apply test-driven development principles to skill creation for robust, reliable skills.

The TDD Cycle

1. Write Test Cases

Define expected behavior before implementation

test_cases:
  - input: "Create a simple todo app"
    expected:
      - Creates app.js file
      - Adds basic HTML structure
      - Includes CSS styling

2. Watch Them Fail

Run tests to verify they fail (Red)

3. Write the Skill

Implement minimal skill to pass tests

4. Watch Tests Pass

Verify all tests pass (Green)

5. Refactor

Improve skill quality, close loopholes

6. Repeat

Add more tests, improve skill iteratively

Test Categories

Happy Path

Expected inputs
Standard use cases
Common scenarios

Edge Cases

Empty inputs
Very large inputs
Special characters
Missing data

Error Handling

Invalid inputs
Missing resources
Conflicting requirements
Resource constraints

Loopholes

Ambiguous instructions
Multiple interpretations
Unclear boundaries
Unstated assumptions

Skill Structure

SKILL.md

---
name: my-skill
description: Clear, specific description
---

# Instructions

Clear, unambiguous instructions that:
- Define scope precisely
- Handle edge cases
- Prevent loopholes
- Specify outputs

Testing Framework

Manual Testing

## Test Case 1
Input: "..."
Expected Output: "..."
Actual Output: "..."
Status: PASS/FAIL

Automated Testing

describe('Skill: my-skill', () => {
  it('should handle basic input', async () => {
    const result = await runSkill('create app');
    expect(result).toContain('app.js');
  });
});

Common Loopholes

Ambiguous Scope

Bad: "Create a website" Good: "Create a single-page HTML website with navigation, hero section, and footer"

Unstated Assumptions

Bad: "Add tests" Good: "Add Jest unit tests for all exported functions with >80% coverage"

Missing Edge Cases

Bad: "Validate email" Good: "Validate email using RFC 5322 standard, handle empty input, very long emails, unicode characters"

Vague Success Criteria

Bad: "Make it better" Good: "Refactor function to be less than 20 lines, have single responsibility, include JSDoc"

Refactoring Skills

After tests pass:

Clarify ambiguous language
Add edge case handling
Close discovered loopholes
Improve examples
Add constraints
Specify formats

Documentation

Examples

Include multiple examples:

Minimal example
Full-featured example
Edge case example

Constraints

Specify limits:

File size limits
Time constraints
Resource limits
Format requirements

Output Format

Define exactly what output looks like:

File structure
Code format
Error messages
Success indicators

Best Practices

Start with simple tests
Add edge cases incrementally
Test one thing at a time
Make tests repeatable
Document test rationale
Keep tests independent
Refactor ruthlessly
Close loopholes as found