Agent Tooling POC

[sh0ji]

bold text here is @dreamwasp's comments! evan hacked out the structure and i tweaked, refactored, agonized, etc. my comments/additions here are in bold and i have striked-thru things i removed.

Reed asked me to put something together that squads could try out this week, and I didn't want to overwrite anything in #3322 with Cass out, so I hacked together a quick POC with Claude. I don't intend to merge this but if any of it proves useful, we can port it to Cass' PR.

I had Claude create the following based on our existing docs, but following the specs for Skills, Rules, and Commands.

It's probably easiest to just browse https://github.com/Codecademy/gamut/tree/evan-poc-agent-tooling/packages/gamut/agent-tools to see the actual markdown files, but I'm including an overview here of my thoughts around each file type.

Files and their purpose

This stuff is all relatively new and as always with AI, it's nondeterministic so I don't think we can say with 100% certainty that agents will always treat these things differently. But we can use them for different purposes—to solve different problems.

• Skills are probably the most standard and useful of the files included. Agents load their frontmatter (name + descriptions) in every prompt, and if the agent decides it's relevant, it loads the whole file.
  • I included a few of these for our systems like ColorMode & Typography, which I had Claude just translate to Skills from our docs.
• Commands (Claude Commands, Cursor Commands) are quite similar to Skills. My mental model for them is that they're runbooks rather than best practices or documentation. They're invoked (e.g., /gamut-review) instead of loaded automatically. I'm unclear on whether their frontmatter gets loaded or not. /gamut-review is now a skill! commands have been deprecated
  • I could see this being useful. I created an example one that audits a repo against Gamut best practices, but could also easily imagine /migrate-to-gamut or similar to incrementally move a project from Percipio UI to Gamut. i agree which is precisely why i migrated to skill~
• Agents (Cursor Agents, Claude Agents) are persona-based files like a "security researcher" or a "copy editor". I'm not sure if we have a use case for this so I didn't include any examples, but I did leave the directory in place with a .gitKeep just to illustrate the concept.
• Rules are only supported by Cursor. Unlike Skills, all rules are always loaded for every prompt, so I'm inclined to say we shouldn't ship any, but I think they're worth testing so I replicated the accessibility skill as a rule so we can compare it against the skill. **we decided to do away with rules~ **
• DESIGN.md is not part of the plugin ecosystem but I think it makes sense to version it along with all the other assets. It was introduced by Google Stitch and is essentially a design system's design language in markdown form.
  • It's supported by Figma and I played around with making it installable with the CLI but that's probably not the best approach since designers don't typically use CLIs like devs do.
  • I added a new tool for this instructions below

Testing Instructions

1. in the project where you're using gamut, yarn add @codecademy/gamut@a68.6.2-alpha.671e56.0. this will just pull the new agent assets as well as the new gamut binary command, which you can run with yarn gamut or npx gamut.
   • if you're testing from within this branch on a local clone, run yarn install to register the new gamut binary.
2. install the plugin in your tool with yarn gamut plugin install cursor|claude|figma.
   • yarn gamut plugin install (without a target) defaults to cursor.
   • yarn gamut plugin install claude installs both the plugin and a custom marketplace.
   • yarn gamut plugin install claude --theme core
     to add the DESIGN.md file, but it might be easier for designers to just copy/paste. I'm not sure about this one.
   • yarn gamut plugin help to see other commands
3. open your tool's plugin UI to verify that the assets exist.
   • Cursor: Cmd + Shift + J then go to Plugins in the sidebar. You should see "Gamut Design System" listed.
   • Claude: claude plugins list. You should see gamut-design-system listed.
4. Also check out the new AI Tooling docs under Meta

[nx-cloud]

View your CI Pipeline Execution ↗ for commit b8f2760

---

☁️ Nx Cloud last updated this comment at 2026-05-27 13:55:07 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.90%. Comparing base (3e85865) to head (b8f2760).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3329      +/-   ##
==========================================
- Coverage   90.40%   89.90%   -0.50%     
==========================================
  Files         405      276     -129     
  Lines        6646     5723     -923     
  Branches     2116     1918     -198     
==========================================
- Hits         6008     5145     -863     
+ Misses        630      570      -60     
  Partials        8        8              

Flag	Coverage Δ
main	?
pull-request	89.90% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jakemhiller]

kinda need to iterate on this, so i think we should ship it 👍

[codecademydev]

📬 Published Alpha Packages:

Package	Version	npm	Diff
@codecademy/gamut	68.6.3-alpha.d1603c.0	npm	diff
@codecademy/gamut-icons	9.57.6-alpha.d1603c.0	npm	diff
@codecademy/gamut-illustrations	0.58.12-alpha.d1603c.0	npm	diff
@codecademy/gamut-kit	0.6.601-alpha.d1603c.0	npm	diff
@codecademy/gamut-patterns	0.10.31-alpha.d1603c.0	npm	diff
@codecademy/gamut-styles	18.0.1-alpha.d1603c.0	npm	diff
@codecademy/gamut-tests	6.0.2-alpha.d1603c.0	npm	diff
@codecademy/variance	0.26.2-alpha.d1603c.0	npm	diff
eslint-plugin-gamut	2.4.4-alpha.d1603c.0	npm	diff

[github-actions]

🚀 Styleguide deploy preview ready!

Preview URL: https://6a16f86032b2d75ac7ed9961--gamut-preview.netlify.app
Deploy Logs: https://app.netlify.com/projects/gamut-preview/deploys/6a16f86032b2d75ac7ed9961