ryan4yin | 二花
f32d67a5cc
Adds the review-comments-and-docs skill (1282-word body) and two evaluation suites: a 21-case measured suite for the skill, and a harness that runs the two concurrency scenarios previously left unrun in agents/evals/global-rules.md.
Global skills
Agent Skills shared by every agent on this machine, deployed into ~/.agents/skills/<name> by
skills.nix. They come from two places:
- Flake inputs (pinned in
flake.lock): linked from the Nix store, so an update is a lock bump plus a Home Manager switch. - This directory (
agents/skills/<name>/): skills iterated on locally, linked out-of-store so an edit applies on the next agent session; adding or removing one needs a switch.
Repository-scoped skills do not belong here; they live in the owning repository's .agents/skills/.
Skills from flake inputs
mattpocock-skills— ryan4yin/mattpocock-skillsmain(fork):diagnosing-bugs,domain-modeling,grill-with-docs,grilling,prototype,research,retro,setup-matt-pocock-skills,wayfinder,writing-for-agentsi-have-adhd— ryan4yin/i-have-adhdmain(fork):i-have-adhdhumanizer— blader/humanizerv3.1.0:humanizerponytail— DietrichGebert/ponytailv5.1.0:ponytail-review
Dependencies travel together: grill-with-docs and wayfinder call grilling and
domain-modeling; wayfinder also calls research and prototype, and points at
setup-matt-pocock-skills for the issue-tracker convention; retro calls writing-for-agents.
User-invoked skills (disable-model-invocation: true, plus allow_implicit_invocation: false in
agents/openai.yaml for Codex) stay out of the model's skill catalog: grill-with-docs,
wayfinder, retro, setup-matt-pocock-skills, and i-have-adhd. The global rules embed the
i-have-adhd always-on snippet, so the skill is only needed for its full ruleset.
The global rules take precedence over these skills. In particular, wayfinder defaults to GitHub
issues and pushes research branches; both are GitHub writes that need authorization, and a public
repository is the wrong place for an infrastructure decision map.
To update one: review the upstream diff as untrusted input, then nix flake update <input> (or move
the pinned tag/commit in flake.nix) and check git diff flake.lock.
Skills in this directory
git-delivery is maintained here rather than pulled from an input: commit messages, PR text, review
replies, and cleanup after merge, all following the target repository's conventions. Edit it in
place; the change reaches the next agent session without a switch.
find-docs is a rewrite of upstash/context7 skills/find-docs (MIT), vendored because the
upstream body drives the CLI with npx ctx7@latest and suggests a global npm install, both of
which the global rules forbid. This one calls the ctx7 that Home Manager installs from nixpkgs
(see packages.nix), and its flags match the packaged
version: 0.5.12 has no --language, which upstream documents. Re-check ctx7 --help when nixpkgs
bumps it.
review-comments-and-docs reviews documentation, inline comments, and API contracts for accuracy,
reader context, scope, and duplication. It preserves intentional history and safety information;
behavioral fixtures test those boundaries. Its
original synthesis drew on
prune-comments-and-docs
(reader-specific fact placement and pruning),
documentation-verification
(source, reference, and factual checks), and
Google Technical Writing: Documents
(audience, scope, and organization around reader needs). That provenance lives here, not in the
skill body, which agents load on every run.
A third-party skill starts here only when it is being rewritten. Until then, pin it as a flake input so the license and provenance stay with the upstream repository and the diff stays reviewable.