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 @writing.md + @operating.md import lines in your ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md. Both tools support @path, so they import the same fragments — no copy, no drift.

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 + ready-to-merge; user clicks merge (canonical CI/review loop)
blitz	drive a whole milestone to done
nightshift	hours-long unattended build; architect delegating to subagents, backs off before the 5h limit
linear-common	shared config/setup/worktree conventions + local verification budget (dependency of work/yolo/blitz/nightshift)
crit, improve-codebase-architecture	misc

Vendored skills

humanizer and impeccable are third-party and copied in, not written here. Each carries an UPSTREAM file recording repo, pinned tag, subdirectory, and license. Do not edit them — a local change becomes a merge conflict on every update, and a rule that reads wrong is a bug to report upstream.

./bin/check-vendored.sh   # reports any that have moved upstream

To update: re-clone at the newer tag, copy the subdir over the skill dir, and bump ref + vendored in UPSTREAM.

skill	upstream	license
humanizer	blader/humanizer	MIT
impeccable	pbakaus/impeccable	Apache-2.0

Writing contract

One contract, claude-md/writing.md, linked three ways: ~/.claude/writing.md (imported via @writing.md), ~/.agents/AGENTS.md (Codex, which has no @import), and the nix module for NixOS machines.

The rule it encodes is selection, not compression: keep output short by cutting whole ideas that don't change what the reader does next, then write what survives as plain sentences. Not by dropping articles, abbreviating, or writing fragments — that is shorter and worse. Anthropic's Fable 5 and Opus 5 prompting guides both say this explicitly.

Two enforcers in hooks/:

enforcer	scope
comms-lint.py	GitHub issues/PRs/review comments — 150 words (hard cap 300), evidence in <details>, no reviewer-addressing opener, plain diction
comment-lint.py	code comments — 1-3 lines, volume and purpose, not wording. The rule is path-scoped (~/.claude/rules/), so it loads only when Claude reads a source file.

Written in the voice it asks for, and leads with a worked example of each. Prompt style leaks into output style, and examples steer harder than prohibitions, so the file is short and shows rather than forbids. Prose alone drifts; the linters make it binding. Details in hooks/README.md.