Repository navigation
Clearer agent tool descriptions, trimmed agent docs, skills in .agents - #19
Merged
Merged
Conversation
The docs agents read had drifted from GLOSSARY.md (swatch grid, colour card, selected cell, commits) and carried template sediment: a multi-context layout this repo doesn't have, example ADRs that don't exist, and notes meant for whoever first filled in the template. AGENTS.md now points at each docs/agents file by when to read it, and stops repeating the label list. The verify-huebo feature map keeps its recipes and leaves conventions and proof rules to SKILL.md, which held the same rules already. Feature files are renamed to grid.md and card.md to match the glossary. verify-dial-motion now says AUTONOMOUS lives in both motion.ts and the check, and names its pstack maintenance skill in full.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Every tool description opened with the same paragraph about Huebo's colour model, so an agent read the model three times before learning what any tool did. Now each description starts with its action, and the model appears once, in choose_colour, the tool that takes stops and steps. choose_colour said "any of hue, saturation and brightness" would work, but a lone saturation throws when nothing is picked, and clearPick or a hex throws when combined. Each field now says what it needs alongside it. The card is "the card", and the 0–100 input is StepInput, not Level.
The skills now live in .agents/skills, where tools other than Claude Code look for them, and .claude is a symlink to .agents, so Claude Code still loads them from .claude/skills. Docs and the oxlint config point at .agents. oxlint ignores .claude, which would otherwise lint the same files a second time through the link.
This branch was successfully deployed
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
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.
Summary
Agent tools, the agent docs, and where the skills live. I checked all three against writing-for-agents. Huebo's behaviour doesn't change, but agents now see different tool descriptions.
Agent tools (
src/picker/agent/tools.ts)Every description opened with the colour model, so an agent read the model three times before learning what any tool did. Now each description starts with its action, and the model appears once, in
choose_colour.choose_colouralso promised more than it accepts. The rules it never mentioned now sit on the fields they apply to:Agent docs
Skills live in
.agentsDocs and
oxlint.config.tspoint at.agents. oxlint ignores.claude/**, because otherwise it lintsinput.mjsa second time through the link and fails onno-console.Evidence
choose_colour({ saturation: 62 })would work. With nothing picked, it throwsNothing is picked yet, so give both saturation and brightness.After: the saturation field says so.
src/picker/agent/__tests__/tools.test.tsx: 19 passed.pnpm lintafter the move:.claude/skills/verify-huebo/input.mjs:156:3: error eslint(no-console)After:
pnpm lint,tsc,check:formatandfallowall pass..claude/skills/verify-huebo/huebo.shstill runs through the link and prints its usage.pnpm verifyprints only the documented open finding (+ then −, 205° on screen).Merge Danger
Door: two-way
Blast Radius: agents
Agents connected over WebMCP get new tool descriptions, but the tools take and return the same things. If something on a contributor's machine reads
.claudeand doesn't follow symlinks, it won't find the skills. Git stores the link as a symlink, so on Windows without symlink support it checks out as a text file.