Skip to content

Clearer agent tool descriptions, trimmed agent docs, skills in .agents - #19

Merged
ericchernuka merged 3 commits into
masterfrom
ec/agent-docs-audit
Nov 10, 2026
Merged

ericchernuka merged 3 commits into
masterfrom
ec/agent-docs-audit

Conversation

@ericchernuka

@ericchernuka ericchernuka commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

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_colour also promised more than it accepts. The rules it never mentioned now sit on the fields they apply to:

 choose_colour
-  "any of hue, saturation and brightness to change just those"
+  saturation / brightness: "With nothing picked yet, give brightness/saturation too."
+  clearPick: "Give it alone or with a hue."
+  hex: "Give it alone."
 choose_format
-  "Huebo's colour card"
+  "Huebo's card"
 requests.ts
-  Level
+  StepInput            # glossary: Step, avoid "level"

Agent docs

 AGENTS.md                      # pointers say when to read each file; label list dropped
 docs/agents/domain.md          # 53 → 21 lines: multi-context template and made-up ADRs gone
 docs/agents/issue-tracker.md   # dropped a no-op line
 docs/agents/triage-labels.md   # dropped the template's "edit this column" note
 verify-huebo/
   features/README.md           # conventions now live only in SKILL.md
-  features/swatch-grid.md
-  features/colour-card.md
+  features/grid.md             # glossary names
+  features/card.md
 verify-dial-motion/SKILL.md    # AUTONOMOUS is in motion.ts and motion.verify.ts

Skills live in .agents

-.claude/skills/…
+.agents/skills/…
+.claude -> .agents             # symlink, so Claude Code still finds .claude/skills

Docs and oxlint.config.ts point at .agents. oxlint ignores .claude/**, because otherwise it lints input.mjs a second time through the link and fails on no-console.

Evidence

  • Before: a description that told agents choose_colour({ saturation: 62 }) would work. With nothing picked, it throws Nothing is picked yet, so give both saturation and brightness.
    After: the saturation field says so. src/picker/agent/__tests__/tools.test.tsx: 19 passed.
  • Before: pnpm lint after the move: .claude/skills/verify-huebo/input.mjs:156:3: error eslint(no-console)
    After: pnpm lint, tsc, check:format and fallow all pass.
  • .claude/skills/verify-huebo/huebo.sh still runs through the link and prints its usage.
  • pnpm verify prints 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 .claude and 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.

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.
@vercel

vercel Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
huebo Ready Ready Preview Nov 10, 2026 4:17am UTC

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.
@ericchernuka ericchernuka changed the title Trim the agent docs and speak the glossary in them Clearer agent tool descriptions, trimmed agent docs, skills in .agents Nov 10, 2026
@ericchernuka
ericchernuka merged commit a97c925 into master Nov 10, 2026
3 checks passed
@ericchernuka
ericchernuka deleted the ec/agent-docs-audit branch November 10, 2026 04:18

This branch was successfully deployed

1 active deployment
Preview — cae900e2 Deployed Nov 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant