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>
40 lines
2.0 KiB
Markdown
40 lines
2.0 KiB
Markdown
---
|
|
name: rules-case-study
|
|
description:
|
|
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
|
|
|
|
1. 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](references/interview-source-map.md) as a routing
|
|
hint, then confirm paths in the target repository.
|
|
2. 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.
|
|
3. 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.
|
|
4. 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.
|
|
5. 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.
|
|
6. 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.
|
|
7. 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.
|