docs: add AGENTS.md guidance#6
Conversation
Add AGENTS.md as the canonical agent guidance (CLAUDE.md points to it), covering the skill-vs-plugin install duality, the .claude/skills symlink, the two-tier pricing design, and the PR-only workflow on protected main. Fix the claude-usage-report marketplace entry: a bare relative-string source combined with a skills array trips Claude Code's plugin resolver into a misleading "update Claude Code" error. Switch to the git-subdir object form used by other skill-bearing plugins. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| - `.claude/skills` is a **symlink** to `.agents/skills`. The repo-local `write-a-skill` skill lives at | ||
| `.agents/skills/write-a-skill/` and is the authoring guide/checklist — use it when adding or changing a skill. |
There was a problem hiding this comment.
Pointing out that .claude/skills is a symlink doesn't seem useful. When following that path, it should land in .agents/skills.
There was a problem hiding this comment.
Now reconsidering this after looking into how Windows really handles POSIX symlinks, I think this could be useful after all. Maybe even more explicitly explain that agents should look in .agents/skills/ instead of .claude/skills/ for repo installed skills. Further, it may be necessary to explain that the skill directories in .agents/skills/ may be symlinks to the skills defined in skills/.
There was a problem hiding this comment.
Put it back with an additional line about potential symlinks to skills/
dumptruckman
left a comment
dumptruckman
left a comment
There was a problem hiding this comment.
Overall, I think there's too much in the AGENTS.md file. The general approach should be to only add things to correct common errant behavior by agents working in the repo.
Cut content that duplicated the README, the write-a-skill skill, or skill-local detail per PR #6 review. Keeps the three things that actually correct errant agent behavior: protected-main workflow, skill-vs-plugin install duality, and the marketplace.json source trap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The git-subdir source fix is being handled in its own PR (#7) so it can merge without waiting on this AGENTS.md review. This branch now carries only the AGENTS.md/CLAUDE.md docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
goneflyin
changed the title
2 participants
Summary
Add AGENTS.md as the canonical guidance for coding agents (Claude Code, Codex, others). CLAUDE.md becomes a thin pointer to it.
AGENTS.md contents
Trimmed to the things that actually correct errant agent behavior in this repo (per review feedback):
mainis protected; changes land via PR only.skills.shcopies skill files only (no hooks/MCP/agents); the plugin path installs hooks too. Non-obvious and easy to get wrong.git-subdirobject form.Content that duplicated the README, the
write-a-skillskill, or a skill's own SKILL.md was removed.Note
The marketplace.json resolver fix that originally rode along with this PR has been split out to #7 so it can merge independently. This branch is docs-only now.
🤖 Generated with Claude Code