docs: add CLAUDE.md and require skills to be checked on every stack change#596
Conversation
…hange Two gaps, one fix. **Claude Code was reading no project instructions in this repo.** It loads `CLAUDE.md`, not `AGENTS.md` (https://code.claude.com/docs/en/memory#agentsmd), and this repo only had the latter. Add a `CLAUDE.md` that imports `@AGENTS.md` so both Claude Code and Codex read one source of truth, rather than duplicating the rules or relying on a symlink (which needs Developer Mode on Windows). **Skills drift silently.** `skills/*/SKILL.md` ship inside the `stash` tarball (`packages/cli/tsup.config.ts` copies them into `dist/skills/`), get copied into the user's `.claude/skills/` or `.codex/skills/` by `installSkills()`, and are inlined into their `AGENTS.md` by `readBundledSkill()`. Nothing type-checks them, so a stale sentence lands in a customer's repo. The stash-cli skill had drifted a whole command surface behind before anyone noticed. - New `## Agent Skills — these ship to customers` section in `AGENTS.md`: how skills reach users, why each `SKILL.md` must stay self-sufficient (only `SKILL.md` is inlined for the agents-md target), a package-to-skill map, and the mechanical check for CLI changes -- diff the skill against `stash manifest --json` rather than proofreading it. - New checklist item 8 in "Adding Features Safely", so the rule is hit at PR time and not only by whoever reads the section. - Note in the changeset item that a skills-only change is not internal: it ships, so it needs a `stash` patch.
|
|
Warning Review limit reached
Next review available in: 2 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR improves agent/developer guidance in the cipherstash/stack repo by adding Claude Code–specific instructions and strengthening the repo-wide policy that shipped skills (skills/*/SKILL.md) must be reviewed alongside product/CLI changes to prevent customer-facing drift.
Changes:
- Add
CLAUDE.mdthat imports@AGENTS.mdand reiterates the two most commonly-missed rules (skills checks + changesets). - Expand
AGENTS.mdwith a new “Agent Skills — these ship to customers” section explaining how skills are packaged/installed/inlined and providing a package→skill checklist. - Update the “Adding Features Safely” checklist to require checking relevant skills, and clarify that skills-only changes require a changeset.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
CLAUDE.md |
Adds Claude Code entrypoint instructions and re-emphasizes skills + changeset rules. |
AGENTS.md |
Documents skills as shipped artifacts, adds a package→skill map, and updates the safety checklist accordingly. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Addresses review on #596. `src/messages.ts` is ambiguous from the repo root -- there is no root `src/` -- so spell it `packages/cli/src/messages.ts`, matching the fully-qualified path next to it. Same for "the command registry", now named as `packages/cli/src/cli/registry.ts`. Swept every backticked path in CLAUDE.md and in the new AGENTS.md section; all resolve.
|
Low impact change, AI review. |
Why
Two gaps, one fix.
1. Claude Code has been reading no project instructions in this repo
Claude Code loads
CLAUDE.md, notAGENTS.md(docs). This repo only hasAGENTS.md, so every Claude Code session here has started with zero project context — no build commands, no gotchas, no bundler warning, no changeset rule.This PR adds a
CLAUDE.mdthat imports@AGENTS.md. One source of truth, read by both Claude Code and Codex. The@import is the documented pattern and is preferred over a symlink, which requires Developer Mode on Windows.2. Skills drift silently, and the damage lands in customer repos
skills/*/SKILL.mdare published artifacts:packages/cli/tsup.config.tscopiesskills/intodist/skills/, so they ship inside thestashnpm tarball.installSkills()copies the per-integration set into the user's.claude/skills/or.codex/skills/at handoff time.readBundledSkill()inlines a skill's body into the user'sAGENTS.mdfor Cursor / Windsurf / Cline.Nothing type-checks them and nothing in CI compares them to the code. A stale sentence becomes wrong guidance in someone else's codebase. This isn't hypothetical:
stash-clihad fallen a whole command surface behind (thedb→eqlmove, four undocumented commands, six wrong API signatures, and three citations of a closed issue) before anyone noticed.What's in it
CLAUDE.md— imports@AGENTS.md, then repeats the two rules that fail silently (check the skills; add a changeset) and points atpackages/cli/AGENTS.mdfor the two-Vitest-config gotcha.AGENTS.md→ new## Agent Skills — these ship to customerssection:How a skill actually reaches a user, so the stakes are concrete.
Why each
SKILL.mdmust stay self-sufficient — onlySKILL.mdis inlined for theagents-mdtarget, so content split into sibling reference files is silently dropped for Cursor/Windsurf/Cline users.A package→skill map, so "which skill do I check?" has an answer.
A mechanical check for CLI changes, since the command registry is the source of truth:
Every command and flag named in
skills/stash-cli/SKILL.mdmust resolve against that manifest. This turns "did anyone proofread the skill?" into a diff.A reminder that skills are public: no Linear issue IDs.
AGENTS.md→ new checklist item 8 in "Adding Features Safely", so the rule is enforced at PR time and not only by whoever happens to read the section.AGENTS.md→ changeset item now notes that a skills-only change is not internal. It ships in thestashtarball, so it needs astashpatch.Verification
tsup.config.ts,install-skills.ts,AGENTS-doctrine.md,packages/cli/AGENTS.md).skills/.CLAUDE.mdis not gitignored.Notes
stash-secrets, which chore: remove the secrets skill and the leftovers from the secrets removal #595 removes.