feat(tools): set up skeleton for AI tooling

[dreamwasp]

Overview

Created tools/ai-tools skeleton including:

• Example plugin layouts under examples/templates/ (one for Cursor, one for Claude Code), with placeholder rules/skills and valid config files.
• A validate check you can run with Nx so those example config files stay valid JSON.
• A helper CLI (agent-manager) copied from our web-platform tooling, mainly so people can install a local plugin folder into Cursor or Claude if they want—optional.

PR Checklist

• Related to designs:
• Related to JIRA ticket: [gm-1589]
• Version plan added/updated (or not needed)
• I have run this code to verify it works
• This PR includes unit tests for the code change
• This PR includes testing instructions tests for the code change
• The alpha package of this PR is passing end-to-end tests in all relevant Codecademy repositories

Testing Instructions

1. Locally run: npx nx run ai-tools:validate from the repo root (should succeed).
2. Skim through folder structure and confirm it makes sense

PR Links and Envs

N/A

[nx-cloud]

View your CI Pipeline Execution ↗ for commit dcfbd3a

---

☁️ Nx Cloud last updated this comment at 2026-04-13 17:53:47 UTC

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

[codecademydev]

📬 Published Alpha Packages:

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

[github-actions]

🚀 Styleguide deploy preview ready!

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

[sh0ji]

Interesting, I hadn't thought of copying that agent-manager cli into here but that certainly works!

Is there a benefit to having separate plugins? I couldn't figure out one when I was hacking at this and just went with one plugin that contains two manifests, but maybe I missed something. I definitely don't think we need any more than one gamut plugin, though.

As far as I can tell, we can structure it as a mashup of Claude's standard plugin layout and Cursor's plugin structure. Smashing those layouts together with manifests for each wasn't really a problem when I was experimenting with this because if one format doesn't support it, it just gets ignored as far as I can tell. And even if that's not true, I'd want to handle that in the "install" process (more likely a new "build" process), not in the source layout. In other words, only copy the supported files on install by incorporating some kind of "supported directories" spec in a new build script, which runs before install and just bundles all the supported files.

Here's an example of what I'm imagining for the actual Gamut plugin:

packages/agent-tools
├── .claude-plugin
│   ├── marketplace.json
│   └── plugin.json
├── .cursor-plugin
│   └── plugin.json
├── agents
│   └── gamut-developer.md
├── commands
│   ├── migrate-to-gamut.md
│   └── review-gamut-usage.md
├── hooks
│   └── hooks.json
├── rules
│   ├── documentation-style-guide.mdc
│   └── accessibility-standards.mdc
├── skills
│   ├── color-mode
│   │   └── SKILL.md
│   ├── system-props
│   │   └── SKILL.md
│   └── using-aria
│       └── SKILL.md
├── mcp.json
├── package.json
└── README.md

1. It's just a package like any other. I'm not sure what the best name is...agent-tools is probably too generic. Maybe gamut-agent-plugin?
2. .claude-plugin and .cursor-plugin are top-level config manifests.
3. All other directories are theoretical solutions that I included to illustrate what this could grow into, not necessarily things that I think we should be shipping. The goal is to support current and future solutions with this layout, so even though we might not know what agent/gamut-developer.md is today for instance, it demonstrates a way we could experiment with something like an independent agent that writes code using Gamut (claude agents, cursor agents).

For this PR, you don't need to create any actual skills/md files. We should have separate PRs (and reviews) for things like color-mode/SKILL.md. This just sets up the structure to start defining those PRs.

[sh0ji]

smart! good call including a validation step.