26a6469604
Includes: - New 'web-search' skill - New 'web-research' skill with multi-backend support (claude, llm, kagi) - Automated deployment in bin/deploy-skill.sh - Sops-nix integration for Kagi API key - Documentation updates
84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# 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 skill to dotfiles
|
|
- Automatically injects configuration into `home/claude.nix` and `home/opencode.nix`
|
|
- Checks for `home/antigravity.nix` and injects global binary configuration if present
|
|
|
|
**Antigravity Support (Global Binaries)**:
|
|
- Antigravity does not auto-load skills like Claude/OpenCode.
|
|
- Instead, we deploy skill scripts to `~/.local/bin/` via Nix.
|
|
- This makes them available as global commands (e.g., `web-search "query"`).
|
|
- Configuration lives in `home/antigravity.nix` (or similar) in dotfiles.
|
|
|
|
**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
|
|
- 003-web-search: Added `web-search` skill and automated deployment injection for Claude, OpenCode, and Antigravity.
|
|
- 002-update-opencode: Added Bash (no specific version requirement - standard POSIX + bash extensions) + `jq`, `curl`, `nix-prefetch-url`, `sed`/`awk`, GitHub API
|