docs: ship an agent reference in the package, plus a Claude Code skill - #7
Merged
Conversation
Adds AGENTS.md to the published files, so it lands at node_modules/@engineio/ui/AGENTS.md and versions with the code. Consuming repos point at that path instead of copying rules into their own CLAUDE.md, where a copy goes stale on the next version bump — and stale brand rules are worse than no brand rules, because they read as authoritative. The content is what an agent actually needs and a human README buries: the @source requirement and why its absence is silent, the three import forms, the variant roster per component, the exact token names, the hard rules as rules rather than prose, the tv({ extend }) seam, and the known gaps. It deliberately repeats almost nothing from README.md, which is written for a person deciding whether to adopt this. Also adds .claude/skills/engine-design-system/SKILL.md. Skills must live in .claude/skills/, ~/.claude/skills/ or a plugin — Claude Code does not load them from node_modules — so the skill is a deliberately thin pointer at the package's AGENTS.md plus the half-dozen rules worth having in mind before reading it. Keeping the substance in the package means the copied file contains nothing that can rot, and a skill body loads lazily so the reference costs nothing until a UI task needs it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
AGENTS.md, shipped in the packageLands at
node_modules/@engineio/ui/AGENTS.mdand versions with the code.Consumers point at that path rather than copying rules into their own
CLAUDE.md— a copy goes stale on the next bump, and stale brand rules areworse than none because they still read as authoritative.
Contents are what an agent needs and the README buries:
@sourcerequirement, and why its absence is silent (half-styled app)tv({ extend })seam.claude/skills/engine-design-system/SKILL.mdSkills must live in
.claude/skills/,~/.claude/skills/or a plugin — ClaudeCode will not load them from
node_modules. So the skill is a thin pointer tothe package's
AGENTS.mdplus the handful of rules worth knowing before readingit. Two consequences, both deliberate:
in the package.
actually needs it.
Consumer side
engine/front/AGENTS.mdandrgs/services/front/AGENTS.mdeach gain a shortpointer section (committed separately in those repos).