dan/skills

dan 5fea49b7c0 feat(tufte-press): evolve skill to complete workflow with JSON generation and build automation

- 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

2025-11-10 15:03:44 -08:00

2.8 KiB

Raw Blame History

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.

2.8 KiB Raw Blame History