naps62
a1f95a1161
Replaces public-comms.md and code-comments.md (749 words, ~25 rules, almost all prohibitions, no examples) with a single writing.md that leads with worked examples. The rule 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 or writing fragments, which Anthropic's Fable 5 guide calls out as the wrong lever. Prompt style leaks into output style, so the file is written in the voice it asks for. Drops the BLUF ask-line rule entirely: everyone on a PR already knows who reviews and who merges, and read literally it produced openers like "Ask: reviewers please merge". Links the contract to ~/.agents/AGENTS.md, which Codex had nothing in at all, and to the nix module for the NixOS machine.
92 lines
4.6 KiB
Markdown
92 lines
4.6 KiB
Markdown
# 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)
|
|
|
|
```sh
|
|
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 `@writing.md` import line in your `~/.claude/CLAUDE.md`. Codex needs no step — `~/.agents/AGENTS.md` is linked directly.
|
|
|
|
### NixOS machine (home-manager)
|
|
|
|
```nix
|
|
# 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".
|
|
|
|
```sh
|
|
~/.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`, `humanizer`, `impeccable`, `improve-codebase-architecture` | misc |
|
|
|
|
## 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 |
|
|
|
|
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`.
|