skills/WORKFLOW.md

# Skill Development Workflow

This document describes the complete workflow for developing, testing, and deploying skills for agentic coding.

## Overview

Skills are developed in this repository and then deployed to either (or both):
- **Claude Code** (`~/.claude/skills/`)
- **OpenCode** (`~/.config/opencode/skills/`)

The workflow supports both manual development and spec-kit-driven development.

## Development Approaches

### Approach 1: Manual Development

Quick iteration for simple skills or updates.

1. **Create skill directory**:
   ```bash
   cp -r skills/template skills/your-skill-name
   ```

2. **Edit SKILL.md**:
   - Update frontmatter (name, description)
   - Fill in "When to Use" section
   - Document the process/instructions
   - List requirements

3. **Add helper scripts** (if needed):
   ```bash
   # Create scripts in skills/your-skill-name/scripts/
   vim skills/your-skill-name/scripts/helper.sh
   chmod +x skills/your-skill-name/scripts/helper.sh
   ```

4. **Add templates** (if needed):
   ```bash
   # Create templates in skills/your-skill-name/templates/
   vim skills/your-skill-name/templates/output-template.txt
   ```

5. **Update README.md**:
   - Write user-facing documentation
   - Include usage examples
   - Document prerequisites

6. **Test locally** (see Testing section below)

### Approach 2: Spec-Kit Development

Structured approach for complex skills or when you want full specification.

1. **Create feature specification**:
   ```bash
   # In OpenCode or Claude Code
   /speckit.specify "Create a skill for [description]"
   ```

2. **Clarify requirements** (if needed):
   ```bash
   /speckit.clarify
   ```

3. **Create implementation plan**:
   ```bash
   /speckit.plan
   ```

4. **Implement the skill**:
   ```bash
   /speckit.implement
   ```

5. **Test and iterate**

The spec-kit approach creates structured documentation in `.specify/specs/` that captures the full design and implementation process.

## Skill Structure

### Required Files

Every skill must have:

```
skill-name/
├── SKILL.md          # Primary skill definition (required)
└── README.md         # User documentation (required)
```

### Optional Components

Add as needed:

```
skill-name/
├── scripts/          # Helper bash scripts
│   └── helper.sh
├── templates/        # File templates for generated content
│   └── template.txt
└── examples/         # Example outputs
    └── example.txt
```

### SKILL.md Structure

The SKILL.md file is what the agent reads. It must include:

**Frontmatter** (YAML):
```yaml
---
name: skill-name
description: One-line description for agent discovery
---
```

**Required Sections**:
1. Title and overview
2. "When to Use" - Explicit triggers
3. Process/Instructions - Step-by-step for agent
4. Requirements - Dependencies

**Optional Sections**:
- Context Gathering
- Helper Scripts
- Templates
- Guidelines
- Error Handling
- Examples

## Testing

### Local Testing

**Option 1: Symlink to agent directory**

For Claude Code:
```bash
ln -s $(pwd)/skills/your-skill-name ~/.claude/skills/your-skill-name
```

For OpenCode:
```bash
ln -s $(pwd)/skills/your-skill-name ~/.config/opencode/skills/your-skill-name
```

**Option 2: Copy for testing**

```bash
# Copy to Claude Code
cp -r skills/your-skill-name ~/.claude/skills/

# Copy to OpenCode
cp -r skills/your-skill-name ~/.config/opencode/skills/
```

### Test Cases

1. **Script Testing** (if skill has scripts):
   ```bash
   # Test each script independently
   cd skills/your-skill-name
   ./scripts/helper.sh --test-args
   ```

2. **Agent Testing**:
   - Open Claude Code or OpenCode
   - Navigate to a test project
   - Use natural language trigger from "When to Use" section
   - Verify agent invokes skill correctly
   - Check output matches expectations

3. **Edge Cases**:
   - Test with missing dependencies
   - Test in non-git repositories (if applicable)
   - Test with empty or minimal input
   - Test error handling

### Validation Checklist

Before deploying:

- [ ] SKILL.md has correct frontmatter
- [ ] "When to Use" section has clear triggers
- [ ] Process instructions are step-by-step
- [ ] All helper scripts are executable
- [ ] README.md has installation instructions
- [ ] Examples are provided
- [ ] Scripts handle errors gracefully
- [ ] Tested with both Claude Code and OpenCode (if applicable)

## Deployment

### Development Deployment

For active development, use symlinks:

```bash
# Claude Code
ln -s $(pwd)/skills/your-skill-name ~/.claude/skills/your-skill-name

# OpenCode
ln -s $(pwd)/skills/your-skill-name ~/.config/opencode/skills/your-skill-name
```

This allows you to edit in the repo and see changes immediately.

### Production Deployment

#### Manual Deployment

Copy skills to the appropriate directories:

```bash
# Deploy to Claude Code
cp -r skills/skill-name ~/.claude/skills/

# Deploy to OpenCode
cp -r skills/skill-name ~/.config/opencode/skills/
```

#### Nix Home Manager Deployment

For NixOS users, add to your home configuration:

```nix
# home.nix or equivalent
{
  # Claude Code skills
  home.file.".claude/skills/your-skill-name" = {
    source = /path/to/skills/skills/your-skill-name;
    recursive = true;
  };

  # OpenCode skills
  home.file.".config/opencode/skills/your-skill-name" = {
    source = /path/to/skills/skills/your-skill-name;
    recursive = true;
  };
}
```

Then rebuild:
```bash
sudo nixos-rebuild switch --flake .#hostname
```

#### OpenCode Plugin Configuration

Ensure the opencode-skills plugin is enabled:

```json
// ~/.config/opencode/config.json
{
  "plugin": ["opencode-skills"]
}
```

## Version Control

### Commit Guidelines

Follow these commit message conventions:

- `feat(skill-name): Add new feature`
- `fix(skill-name): Fix bug in script`
- `docs(skill-name): Update documentation`
- `refactor(skill-name): Restructure code`
- `test(skill-name): Add tests`

### Branching Strategy

For new skills:
```bash
git checkout -b feature/new-skill-name
```

For updates:
```bash
git checkout -b fix/skill-name-issue
```

### Pull Request Template

When submitting a skill:

```markdown
## Skill: [Name]

### Description
[Brief description of what the skill does]

### Testing
- [ ] Tested with Claude Code
- [ ] Tested with OpenCode
- [ ] Scripts are executable
- [ ] Examples included
- [ ] Documentation complete

### Deployment Notes
[Any special deployment considerations]
```

## Troubleshooting

### Skill Not Discovered

**Claude Code:**
- Check file exists: `ls ~/.claude/skills/skill-name/SKILL.md`
- Verify frontmatter is valid YAML
- Restart Claude Code
- Check Claude Code logs

**OpenCode:**
- Check file exists: `ls ~/.config/opencode/skills/skill-name/SKILL.md`
- Verify opencode-skills plugin is enabled
- Restart OpenCode
- Check plugin loaded: Look for skills in OpenCode output

### Scripts Fail

- Verify scripts are executable: `chmod +x scripts/*.sh`
- Test scripts independently
- Check for missing dependencies
- Verify paths are correct (use absolute paths when possible)

### Agent Doesn't Use Skill

- Make "When to Use" section more explicit
- Use more specific trigger phrases in user request
- Check description in frontmatter is clear
- Verify skill is appropriate for the task

## Best Practices

### 1. Clear Triggers

Make the "When to Use" section explicit:

**Good**:
```markdown
## When to Use

Invoke this skill when the user requests:
- "Create a worklog"
- "Document today's work"
- "Write a session summary"
```

**Bad**:
```markdown
## When to Use

Use this for documentation.
```

### 2. Step-by-Step Instructions

The agent needs procedural instructions:

**Good**:
```markdown
1. Gather git context using: `git status`
2. Run helper script: `./scripts/extract-metrics.sh`
3. Read template from: `./templates/output.txt`
4. Fill in template with gathered information
5. Save to: `docs/output/YYYY-MM-DD-topic.txt`
```

**Bad**:
```markdown
Gather information and create output.
```

### 3. Self-Contained Scripts

Scripts should work from any directory:

**Good**:
```bash
#!/usr/bin/env bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"

# Use absolute paths
cat "$SKILL_DIR/templates/template.txt"
```

**Bad**:
```bash
#!/usr/bin/env bash
cat templates/template.txt  # Fails if not in skill directory
```

### 4. Error Handling

All scripts should handle errors:

```bash
#!/usr/bin/env bash
set -euo pipefail  # Exit on error, undefined vars, pipe failures

# Check prerequisites
if ! command -v git &> /dev/null; then
    echo "Error: git not found" >&2
    exit 1
fi

# Validate input
if [ $# -lt 1 ]; then
    echo "Usage: $0 <argument>" >&2
    exit 1
fi
```

### 5. Documentation

Every skill needs both SKILL.md (for agent) and README.md (for humans):

- **SKILL.md**: Procedural, step-by-step, for agent execution
- **README.md**: Conceptual, examples, for human understanding

## Examples

### Simple Skill (No Scripts)

```
hello-world/
├── SKILL.md          # Instructions for agent
└── README.md         # User documentation
```

SKILL.md might instruct the agent to simply output a greeting based on context.

### Complex Skill (Full Structure)

```
worklog/
├── SKILL.md                      # Agent instructions
├── README.md                     # User guide
├── scripts/
│   ├── extract-metrics.sh        # Git statistics
│   ├── suggest-filename.sh       # Filename generation
│   └── find-related-logs.sh      # Search previous logs
├── templates/
│   └── worklog-template.org      # Output template
└── examples/
    └── example-worklog.org       # Sample output
```

The agent follows SKILL.md to orchestrate all components.

## Contributing

See [README.md](./README.md) for contribution guidelines.

## See Also

- [README.md](./README.md) - Repository overview
- [skills/template/](./skills/template/) - Template for new skills
- [Claude Code Skills Documentation](https://docs.claude.com/en/docs/claude-code/skills)
- [OpenCode Skills Plugin](https://github.com/opencode-ai/opencode-skills)