# skills Development Guidelines

## Project Type
Repository for AI agent skills (Claude Code & OpenCode). Skills are Markdown documentation + Bash scripts deployed to `~/.claude/skills/` and `~/.config/opencode/skills/`.

## Testing & Validation
```bash
# Syntax check bash scripts
bash -n skills/<skill-name>/scripts/*.sh

# Test script directly
./skills/<skill-name>/scripts/script-name.sh [args]

# Test skill locally (symlink for live development)
ln -s $(pwd)/skills/<skill-name> ~/.claude/skills/<skill-name>-test

# Deploy to dotfiles (copies skill, shows Nix config)
./bin/deploy-skill.sh <skill-name>
```

## Bash Script Requirements
- Shebang: `#!/usr/bin/env bash`
- Error handling: `set -euo pipefail` (always)
- Audit logging: `logger -t <tag>` for security-sensitive operations
- Variables: `UPPER_CASE` constants, `lower_case` locals
- Error output: `echo "Error: message" >&2` then `exit 1`
- Dependency checks: `command -v jq >/dev/null || { echo "Error: jq required" >&2; exit 1; }`
- JSON parsing: `jq` with `--arg` for variable substitution (never string interpolation)

## Skill Structure Requirements
**SKILL.md** (agent reads this):
- YAML frontmatter: `name`, `description`
- Required sections: When to Use, Process (step-by-step), Requirements
- Optional sections: Helper Scripts, Templates, Guidelines, Error Handling

**README.md** (humans read this):
- Installation instructions, usage examples, prerequisites

**Security**: Include SECURITY.md with threat model for security-sensitive skills

## Skill Deployment Strategy

**This repo is for development only** - skills live in `skills/<name>/` but are not deployed here.

**Global Skills** (system-wide, all projects):
- Develop in: `~/proj/skills/skills/<name>/`
- Copy to: `~/proj/dotfiles/claude/skills/<name>/` (or target system's dotfiles)
- Nix deploys to: `~/.claude/skills/<name>/` and `~/.config/opencode/skills/<name>/`
- Use for: Reusable capabilities (worklog, screenshot-latest, niri-window-capture)

**Project-Local Skills** (specific repository only):
- Claude: `<project>/.claude/skills/<name>/`
- OpenCode: `<project>/.opencode/skills/<name>/`
- Auto-loaded when working in that directory
- Use for: Project-specific skills that don't apply elsewhere
- Not version controlled (add to .gitignore)

**Project-Local Commands** (OpenCode only, simple workflows):
- Location: `<project>/.opencode/command/<name>.md`
- Simpler than skills - just markdown with instructions
- Use for: Quick project-specific commands (test, deploy, rebuild)
- Example: This repo has `/speckit.*` commands in `.opencode/command/`

**Deployment tool**: `./bin/deploy-skill.sh <skill-name>` (copies to dotfiles, shows Nix config)

**Note on Agents**: OpenCode agents (Build/Plan/custom) use Tab to switch. Agents are modes/personalities, not skills. Skills work with all agents. Per-agent skill filtering not supported.