5fea49b7c0
- Transform tufte-press from reference guide to conversation-aware generator - Add JSON generation from conversation context following strict schema - Create build automation scripts with Nix environment handling - Integrate CUPS printing with duplex support - Add comprehensive workflow documentation Scripts added: - skills/tufte-press/scripts/generate-and-build.sh (242 lines) - skills/tufte-press/scripts/build-card.sh (23 lines) Documentation: - Updated SKILL.md with complete workflow instructions (370 lines) - Updated README.md with usage examples (340 lines) - Created SKILL-DEVELOPMENT-STRATEGY-tufte-press.md (450 lines) - Added worklog: 2025-11-10-tufte-press-skill-evolution.org Features: - Agent generates valid JSON from conversation - Schema validation before build (catches errors early) - Automatic Nix shell entry for dependencies - PDF build via tufte-press toolchain - Optional print with duplex support - Self-contained margin notes enforced - Complete end-to-end testing Workflow: Conversation → JSON → Validate → Build → Print Related: niri-window-capture, screenshot-latest, worklog skills
67 lines
2.8 KiB
Markdown
67 lines
2.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 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.
|