Agent Tooling POC

[sh0ji]

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.
  • 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.
• 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.
• 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.

Testing Instructions

1. in the project where you're using gamut, yarn add @codecademy/gamut@alpha.3329. 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 figma is a bit more experimental. it looks for a figma.config.json file to figure out where 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.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a90891b

---

☁️ Nx Cloud last updated this comment at 2026-04-22 15:20:43 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.19%. Comparing base (2a9d841) to head (a90891b).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3329      +/-   ##
==========================================
- Coverage   89.88%   89.19%   -0.69%     
==========================================
  Files         377      250     -127     
  Lines        5593     4701     -892     
  Branches     1808     1591     -217     
==========================================
- Hits         5027     4193     -834     
+ Misses        558      500      -58     
  Partials        8        8              

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

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.

[codecademydev]

📬 Published Alpha Packages:

Package	Version	npm	Diff
@codecademy/gamut	68.2.3-alpha.b8b211.0	npm	diff
@codecademy/gamut-icons	9.57.3-alpha.b8b211.0	npm	diff
@codecademy/gamut-illustrations	0.58.10-alpha.b8b211.0	npm	diff
@codecademy/gamut-kit	0.6.593-alpha.b8b211.0	npm	diff
@codecademy/gamut-patterns	0.10.29-alpha.b8b211.0	npm	diff
@codecademy/gamut-styles	17.13.2-alpha.b8b211.0	npm	diff
@codecademy/gamut-tests	5.3.4-alpha.b8b211.0	npm	diff
@codecademy/variance	0.26.2-alpha.b8b211.0	npm	diff
eslint-plugin-gamut	2.4.4-alpha.b8b211.0	npm	diff

[github-actions]

🚀 Styleguide deploy preview ready!

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