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:

   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):

   # 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):

   # 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:

   # In OpenCode or Claude Code
   /speckit.specify "Create a skill for [description]"
   

2. Clarify requirements (if needed):

   /speckit.clarify
   

3. Create implementation plan:

   /speckit.plan
   

4. Implement the skill:

   /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):

---
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:

ln -s $(pwd)/skills/your-skill-name ~/.claude/skills/your-skill-name

For OpenCode:

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

Option 2: Copy for testing

# 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):

   # 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:

# 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:

# 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:

# 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:

sudo nixos-rebuild switch --flake .#hostname

OpenCode Plugin Configuration

Ensure the opencode-skills plugin is enabled:

// ~/.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:

git checkout -b feature/new-skill-name

For updates:

git checkout -b fix/skill-name-issue

Pull Request Template

When submitting a skill:

## 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:

## When to Use

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

Bad:

## When to Use

Use this for documentation.

2. Step-by-Step Instructions

The agent needs procedural instructions:

Good:

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:

Gather information and create output.

3. Self-Contained Scripts

Scripts should work from any directory:

Good:

#!/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:

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

4. Error Handling

All scripts should handle errors:

#!/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 for contribution guidelines.

See Also

• README.md - Repository overview
• skills/template/ - Template for new skills
• Claude Code Skills Documentation
• OpenCode Skills Plugin