skills/AGENTS.md

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

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

Active Technologies

• Bash (no specific version requirement - standard POSIX + bash extensions) + jq, curl, nix-prefetch-url, sed/awk, GitHub API (002-update-opencode)
• Filesystem - modifies ~/proj/dotfiles/pkgs/opencode/default.nix (002-update-opencode)

Recent Changes

• 002-update-opencode: Added Bash (no specific version requirement - standard POSIX + bash extensions) + jq, curl, nix-prefetch-url, sed/awk, GitHub API