agent-skills

Single source of truth for custom agent skills + commands. Shared across Claude Code and Codex, every machine.

Layout

skills/      # SKILL.md dirs — Claude Code AND Codex both read these (open Agent Skills standard)
commands/    # slash commands — Claude Code only (Codex ignores)
hooks/       # Claude Code hooks — see hooks/README.md, wiring is manual
claude-md/   # CLAUDE.md fragments — linked to ~/.claude/, imported via @name.md
bin/link.sh  # bootstrap symlinks for non-Nix machines
nix/home.nix # home-manager module for NixOS machines
flake.nix    # exposes homeModules.default

Skills are portable: only name+description frontmatter is required by both tools; Claude-only fields (user-invocable, args) are ignored by Codex. Cross-skill refs use root-relative paths (linear-common/COMMON.md), so they resolve under ~/.claude/skills and ~/.agents/skills alike.

Install

Non-Nix machine (e.g. dev VM)

git clone https://git.naps.pt/yolo/agent-skills.git ~/tea/yolo/agent-skills
~/tea/yolo/agent-skills/bin/link.sh

Symlinks each skill into ~/.claude/skills/ and ~/.agents/skills/, commands into ~/.claude/commands/, hooks into ~/.claude/hooks/, claude-md/ fragments into ~/.claude/. Idempotent; any pre-existing real dir is moved to ~/.agent-skills-backup/ (outside the discovery path, so it isn't picked up as a duplicate skill). Re-run after adding a skill.

Hooks and fragments need one manual step each: the settings.json snippet in hooks/README.md, and an @public-comms.md / @code-comments.md import line in your ~/.claude/CLAUDE.md.

NixOS machine (home-manager)

# flake inputs
inputs.agent-skills.url = "git+https://git.naps.pt/yolo/agent-skills.git";

# home config imports
imports = [ inputs.agent-skills.homeModules.default ];

recursive = true links files individually, so machine-local skills can coexist in the same dir. nixos-rebuild switch to apply/update.

Shared machine, many sessions

Several autonomous runs share one box. skills/linear-common/scripts/gate.sh is a machine-wide semaphore for heavy commands (full test suites, whole-project builds): bounded slots, memory + CPU cap via a systemd user scope, pinned build/test parallelism. Skills run scoped checks in the inner loop and put only the once-per-push full suite through the gate; exit 75 means it never ran and CI takes over. Policy lives in linear-common/COMMON.md under "Local verification budget".

~/.claude/skills/linear-common/scripts/gate.sh --status
AGENT_GATE_SLOTS=3 AGENT_GATE_MEM_MAX=4G ~/.claude/skills/linear-common/scripts/gate.sh -- cargo test

Adding a skill

Drop a new skills/<name>/SKILL.md (+ optional scripts/, references/, assets/). Commit. Non-Nix: re-run bin/link.sh. Nix: rebuild.

Skills

skill	what
work	tracker issue → worktree → PR → hands off to land
yolo	quick ship; optional land handoff
land	drive an open PR to green + merged (canonical CI/review loop)
blitz	drive a whole milestone to done
linear-common	shared config/setup/worktree conventions + local verification budget (dependency of work/yolo/blitz/nightshift)
crit, humanizer, impeccable, improve-codebase-architecture	misc

Writing contracts

Two prose contracts in claude-md/, each with a matching enforcer in hooks/:

fragment	enforcer	scope
public-comms.md	comms-lint.py	GitHub issues/PRs/review comments — BLUF, ≤300 words above the fold, evidence in <details>
code-comments.md	comment-lint.py	code comments — volume and purpose, not wording

Prose alone drifts; the linters make the contract binding. Details in hooks/README.md.