Tutorial Overview

Series index: Superpowers Tutorial Series

writing-skills is the meta-skill of Superpowers. It teaches you how to create new skills. By following this tutorial, you will learn how to extend the Superpowers skill library and build custom skills for your team.

What you will learn

• ✅ The standard structure of a skill
• ✅ The TDD documentation method
• ✅ Skill testing strategies
• ✅ Trigger design
• ✅ A real-world skill development case

Why Create Custom Skills?

The limits of standard skills

Standard skills cover common scenarios, but they may still miss:
- Team-specific workflows
- Industry-specific standards
- Company-specific compliance requirements
- Project-specific best practices

The value of custom skills

flowchart TD
    A[Team needs] --> B[Create custom skill]
    B --> C[Standardize workflow]
    C --> D[New members ramp up faster]
    C --> E[Consistent AI behavior]
    C --> F[Knowledge retention]
    
    style B fill:#e1f5ff
    style C fill:#e8f5e9

Use cases

Skill Structure Details

Standard skill file structure

skills/
└── your-skill-name/
    ├── SKILL.md           # Main skill document (required)
    ├── TEST.md            # Test document (recommended)
    ├── examples/          # Example directory (recommended)
    │   ├── good/          # Good examples
    │   └── bad/           # Bad examples
    └── resources/         # Reference resources (optional)

Standard SKILL.md structure

# skill-name

[A one-line description of what the skill does]

## Trigger

[Trigger conditions - when this skill should be used]

## Behavior

[Behavior description - what the skill should do]

## Process

[Process steps - the detailed execution flow]

## Output

[Output requirements - what should be produced]

## Examples

[Examples - good and bad comparisons]

## Anti-patterns

[Anti-patterns - behavior to avoid]

## Related Skills

[Related skills - relationships to other skills]

TDD Documentation Method

writing-skills uses a Test-Driven Documentation approach:

flowchart TD
    A[Define the skill goal] --> B[Write test scenarios]
    B --> C[Define success criteria]
    C --> D[Write the skill document]
    D --> E[Run test validation]
    E --> F{Tests pass?}
    F -->|No| G[Revise the skill document]
    G --> E
    F -->|Yes| H[Skill complete]
    
    style B fill:#ffebee
    style C fill:#ffebee
    style H fill:#e8f5e9

Step 1: Define the skill goal

## Skill Goal Template

**Skill name**: [a concise, descriptive name]

**Problem to solve**:
[What is missing right now? Why is this skill needed?]

**Target users**:
[Who will use this skill?]

**Success criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

Example:

**Skill name**: deploying-to-production

**Problem to solve**:
The team does not have a consistent process for production deployments, which leads to:
- missed pre-deployment checks
- unclear rollback plans
- delayed notifications

**Target users**:
- Engineering team
- DevOps engineers
- AI coding assistants

**Success criteria**:
- [ ] Automated pre-deployment checklist
- [ ] Rollback plan must be explicit
- [ ] Stakeholders are notified automatically

Step 2: Write test scenarios

## Test Scenarios

### Scenario 1: Normal trigger

**Input**: "Prepare to deploy to production"

**Expected behavior**:
1. The skill is triggered
2. A deployment checklist is shown
3. A rollback plan is requested
4. A deployment plan is generated

**Expected output example**:
```markdown
## Pre-Deployment Checklist

Before deploying, confirm the following:

### Code checks
- [ ] All tests pass
- [ ] Code review complete
- [ ] No known critical bugs

### Rollback plan
Please describe the rollback plan:
[Wait for user input]

### Notification list
Stakeholders to notify:
[Wait for user input]

### Scenario 2: Edge case

**Input**: "Quick deploy, skip checks"

**Expected behavior**:
1. The skill is triggered
2. The importance of checks is emphasized
3. A fast path is offered, but confirmation is still required

**Expected output**:
```markdown
⚠️ I understand you need a fast deployment, but to keep production stable,
the following checks are required:

**Minimum checklist**:
- [ ] Critical tests pass
- [ ] Rollback plan confirmed

If you want to skip the full checklist, confirm:
"I understand the risk and confirm to continue"

### Scenario 3: Non-trigger case

**Input**: "Deploy to the test environment"

**Expected behavior**:
- The skill does not trigger (this is a production deployment skill)
- Another skill may handle it instead

**Validation**:
- Confirm that the skill stays silent

Step 3: Define success criteria

## Detailed Success Criteria

### Functional criteria
- [ ] Trigger accuracy > 95%
- [ ] Output format is consistent
- [ ] The checklist is complete

### Non-functional criteria
- [ ] Response time < 5 seconds
- [ ] Output is concise and clear
- [ ] Easy to understand and follow

### Edge cases
- [ ] Handles skip-check requests
- [ ] Handles partially missing information
- [ ] Handles urgent deployment scenarios

Writing the Skill Document

Trigger section

## Trigger

**Automatic triggers**:
- "Deploy to production"
- "Release a new version"
- "push to production"
- "Ship the new feature"

**Manual triggers**:
- "Use the deploying-to-production skill"
- "Help me prepare the deployment"

**Do not trigger**:
- "Deploy to the test environment"
- "Deploy to staging"
- "Local testing"

Behavior section

## Behavior

When triggered, the skill should:

1. **Present a checklist**
   - Code checks
   - Test checks
   - Documentation checks

2. **Request key information**
   - Rollback plan
   - Notification list
   - Deployment window

3. **Generate a deployment plan**
   - Step-by-step instructions
   - Validation steps
   - Monitoring metrics

Process section

## Process

### Phase 1: Pre-deployment checks

1. Show the checklist
2. Confirm items one by one
3. Record the results

### Phase 2: Risk assessment

1. Assess the scope of change
2. Confirm the rollback plan
3. Identify risk points

### Phase 3: Deployment planning

1. Generate a detailed plan
2. Confirm the schedule
3. Assign responsibilities

### Phase 4: Execute deployment

1. Follow the steps in order
2. Verify after each step
3. Record the results

### Phase 5: Post-deployment verification

1. Run smoke tests
2. Check monitoring metrics
3. Confirm the feature is working

Output section

## Output

The skill should produce:

### Deployment check report
```markdown
## Deployment Check Report

**App**: my-app
**Version**: v1.2.3
**Time**: 2026-02-28 15:00

### Check results
- Code checks: ✅ Passed
- Test checks: ✅ Passed
- Documentation checks: ✅ Passed

### Risk assessment
Risk level: Low
Rollback plan: Confirmed

### Approval
[ ] Technical lead approval
[ ] Product manager approval

Deployment instructions

## Deployment Steps

1. Pull the latest code
   ```bash
   git pull origin main

2. Build

   npm run build
   

3. Deploy

   ./deploy.sh production
   

4. Verify

   curl https://api.example.com/health
   

Skill Testing Strategy

Test types

## Test Types

### 1. Trigger tests
Verify the skill triggers in the right situations and not in the wrong ones

### 2. Output tests
Verify the format and content of the output match expectations

### 3. Process tests
Verify the skill flow is complete

### 4. Edge tests
Verify edge cases are handled correctly

Test template

## Test Cases

### Test 1: Standard deployment flow

**Input**:

Help me deploy to production

**Expected**:
1. ✅ Skill triggers
2. ✅ A checklist is shown
3. ✅ A rollback plan is requested

**Verification command**:
```bash
# Check the skill logs
cat .superpowers/logs/deploy-*.log

Test 2: Skip-check request

Input:

Quick deploy, skip checks

Expected:

1. ✅ Skill triggers
2. ✅ A risk warning is shown
3. ✅ Confirmation is required

Verification:

• Confirm the output includes a risk warning
• Confirm explicit confirmation is required

Test 3: Test environment deployment

Input:

Deploy to the test environment

Expected:

1. ❌ Skill does not trigger
2. ℹ️ Another skill may be suggested

Verification:

• Confirm the skill stays silent

## Real-World Example: Create a Team Code Standards Skill

### Example background

The team has its own coding standards, and it needs AI to follow them during code review:

```markdown
# team-code-review

## Trigger

- When a feature is finished
- When code review is requested
- Before a PR is submitted

## Behavior

Review code according to team standards, with a focus on:
1. Naming conventions
2. Function length
3. Comment requirements
4. Error handling
5. Test coverage

## Team Standards

### Naming conventions
- Variables: camelCase
- Classes: PascalCase
- Constants: UPPER_SNAKE_CASE
- Private members: _prefix

### Function requirements
- Maximum length: 30 lines
- Parameter count: <= 5
- JSDoc required

### Comment requirements
- Public APIs must have JSDoc
- Complex logic must have explanatory comments
- No redundant "what it does" comments

### Error handling
- All exceptional cases must be handled
- Error messages must be clear
- Log for debugging

### Test requirements
- Unit test coverage >= 85%
- 100% coverage for critical paths
- Include edge-case tests

## Output Format

## Code Review Report

**File**: [file path]
**Reviewer**: AI Assistant

### ✅ Complies with standards
- [List compliant items]

### ⚠️ Needs improvement
- [List non-compliant items and suggestions]

### 📋 Checklist
- [ ] Naming conventions
- [ ] Function length
- [ ] Comments complete
- [ ] Error handling
- [ ] Test coverage

Best Practices

1. Skill naming

✅ Good:
- test-driven-development
- systematic-debugging
- using-git-worktrees

❌ Bad:
- tdd (abbreviation is unclear)
- debug (too broad)
- git (too broad)

2. Trigger design

✅ Good:
- Natural-language trigger phrases (multiple synonyms)
- Context-aware triggering
- Clear exclusion conditions

❌ Bad:
- A single trigger phrase
- Too broad
- No exclusion conditions

3. Output format

✅ Good:
- Structured (Markdown)
- Clear sections
- Executable code blocks

❌ Bad:
- Large blocks of prose
- No formatting
- Vague descriptions

4. Test coverage

✅ Good:
- Normal scenario tests
- Edge case tests
- Negative scenario tests

❌ Bad:
- Only one test
- No edge tests
- No failure scenarios

5. Version control

## Version History

### v1.0.0 (2026-02-28)
- Initial version
- Basic checklist
- Standard output format

### v1.1.0 (2026-03-15)
- Added fast-path deployment flow
- Improved risk assessment
- Refined output format

### v2.0.0 (2026-04-01)
- Added automated check integration
- Supported multiple environments
- Improved rollback flow

Publishing and Sharing

Share with the team

## Release Process

1. **Internal review**
   - Team members review the skill document
   - Run all test scenarios
   - Collect feedback

2. **Pilot use**
   - Choose 1-2 projects for a pilot
   - Collect usage feedback
   - Iterate and improve

3. **Formal release**
   - Update the skill repository
   - Notify team members
   - Provide training docs

4. **Ongoing maintenance**
   - Review and update regularly
   - Collect usage data
   - Fix issues

Publish to the community

## Publish to the Superpowers Marketplace

1. **Prepare for release**
   - Complete skill documentation
   - Complete test cases
   - Usage examples

2. **Submit to the Marketplace**
   - Create a PR to superpowers-marketplace
   - Follow the submission guidelines
   - Respond to review comments

3. **After release**
   - Collect user feedback
   - Keep improving
   - Maintain the docs

Summary

writing-skills is the meta-skill for extending Superpowers:

1. TDD documentation - write tests before writing docs
2. Standard structure - Trigger/Behavior/Process/Output
3. Complete testing - normal, edge, and negative scenarios
4. Continuous iteration - versioning and maintenance

Key takeaways

• ✅ Define the skill goal and success criteria clearly
• ✅ Write test scenarios before writing the documentation
• ✅ Follow the standard structure
• ✅ Cover the full testing surface

Skill template quick reference

# skill-name

[One-line description]

## Trigger
[Trigger conditions]

## Behavior
[Behavior description]

## Process
[Process steps]

## Output
[Output requirements]

## Examples
[Examples]

## Anti-patterns
[Anti-patterns]

## Related Skills
[Related skills]

Superpowers Tutorial Series Summary

Congratulations on completing all 10 tutorials. You now understand:

Keep learning:

• Visit the GitHub repository
• Join the community discussion
• Share your custom skills

Series navigation:

• ← Previous: Tutorial 9: verification-before-completion and finishing-a-branch
• Back: Tutorial Series Index

Reference Resources

• Superpowers official repository
• Superpowers Marketplace
• writing-skills skill documentation
• Prompt engineering best practices