yolo/agent-skills
3
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: one writing contract for Claude Code and Codex

Browse Source 
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.
This commit is contained in:
naps62
2026-08-01 13:06:38 +00:00
parent 17677c18df
commit a1f95a1161
9 changed files with 197 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
hooks/README.md
+3 -3
View File
@@ -4,8 +4,8 @@ Claude Code hooks. Claude-only — Codex ignores. `bin/link.sh` / `nix/home.nix`
| hook | event | what |
|------|-------|------|
| `comms-lint.py` | `PreToolUse` / `Bash` | Gates `gh issue\|pr create\|edit\|comment\|review`. Lints body against `claude-md/public-comms.md` (BLUF, ≤300 words above fold, ≤4 bold spans, no essay headings, table for 3+ options). Exit 2 blocks, stderr becomes feedback. |
| `comment-lint.py` | `PostToolUse` / `Write\|Edit\|MultiEdit` | Lints newly-added comment lines in code files against `claude-md/code-comments.md`. Exit 2 = revise nudge (edit already applied). Long-comment-run finding is advisory, delivered via `additionalContext`. |
| `comms-lint.py` | `PreToolUse` / `Bash` | Gates `gh issue\|pr create\|edit\|comment\|review`. Lints body against `claude-md/writing.md` (150-word target / 300 hard cap above fold, no reviewer-addressing opener, plain diction, ≤4 bold spans, no essay headings). Exit 2 blocks, stderr becomes feedback. |
| `comment-lint.py` | `PostToolUse` / `Write\|Edit\|MultiEdit` | Lints newly-added comment lines in code files against `claude-md/writing.md`. Exit 2 = revise nudge (edit already applied). Long-comment-run finding (>3 lines) is advisory, delivered via `additionalContext`. |
Both fail open on anything they can't parse. Debug with `COMMS_LINT_DEBUG=1` / `COMMENT_LINT_DEBUG=1`.
@@ -28,7 +28,7 @@ Both fail open on anything they can't parse. Debug with `COMMS_LINT_DEBUG=1` / `
}
```
Contract prose lives in `claude-md/`, linked to `~/.claude/<name>.md` and imported from `~/.claude/CLAUDE.md` via `@public-comms.md` / `@code-comments.md`. Both linters cite those paths in their block message — moving a fragment means updating the linter string too.
Contract prose lives in `claude-md/writing.md`, linked to `~/.claude/writing.md` and imported from `~/.claude/CLAUDE.md` via `@writing.md`. Both linters cite that path in their block message — moving the fragment means updating the linter string too.
## Testing a hook