Marcos Paulo
ab2308441c
The repository had two skill directories. `skills/` held the four written for this project; `.agents/skills/` held the ones the agent context refers to. Nothing said which an agent should read, and `.agents/ORCHESTRATOR.md` only ever pointed at the second. Move the first four into `.agents/skills/` so there is one location, and add the vendored packages this chapter work used: `animation-vocabulary` and `improve-animations` (emilkowalski/skills), `teach` (mattpocock/skills), plus a local `translation` skill and `audit-translations.mjs` for the EN/PT pairs. `skills-lock.json` pins the vendored three by source and content hash, so a later re-vendor is a diff rather than a guess. `.claude/skills/` is symlinks into `.agents/skills/`, which is what makes them loadable here without a second copy on disk. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.0 KiB
2.0 KiB
name, description
| name | description |
|---|---|
| rules-case-study | Use when explaining how a repository turns agent guidance into enforceable behavior across context files, skills, CLI checks, Git hooks, CI, worktrees, or PR review; build a concise, source-linked case-study page. |
Rules case study
Show the control loop: context → skills → CLI → commit → review. The reader should see where a rule lives, what executes it, and how to verify it.
Workflow
- Inspect authoritative files before writing copy. Start with the repository context file, skill directory, command or database ledger, enforcement scripts, hooks, staged-file config, CI, and review policy. Use the interview source map as a routing hint, then confirm paths in the target repository.
- Separate guidance from enforcement. A context file or skill teaches an agent; a CLI check, hook, CI job, or reviewer blocks or reports behavior. Never describe prose as mechanically enforced.
- For every example, show the rule, exact source path, enforcement point, verification command, and remaining gap. Prefer one concrete ratchet or hook example over a list of vague best practices.
- Add a skills shelf. Each skill needs a trigger, the lesson it carries, a tiny example, and a source link. Keep examples short enough to copy into an agent prompt.
- Include a read-only exploration prompt that asks an agent to map rules to evidence and gaps. Add copy feedback and bilingual labels if the host guide supports both languages.
- Use a dependency-free standalone page when the case study is mostly explanatory. Link back to the main guide and exact source files. Do not modify the source repository merely to document it.
- Verify dynamic stage and skill states, source links, copy behavior, language switching, no horizontal overflow, and the 390px/1920px/3840px viewports. The page is done when every claim has a source or is clearly labeled as a design recommendation.