agent-skills
CLAUDE.md2 starsChanged 3 months agoMITView on GitHub
This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called vp. Vite+ is distinct from Vite, and it invokes Vite through vp dev and vp build. Run vp help to print a list of commands and vp <command> --help for information about a specific command. Docs are local at node_modules/vite-plus/docs or online at https://viteplus.dev/guide/.
- Installs packages
In this repository8 other files it gives its agents.
- agent-config-auditSkill
- changesetSkill
- dep-updates-combinerSkill
- tddSkill
- explain-clearlySkill
- mentorSkill
- walkthroughSkill
- us-english-spelling-sweepSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 86
Every skill change needs a changeset, keyed by the skill's directory name.
- Very specific: line 87
Never touch the version in .claude-plugin/plugin.json, a skill's CHANGELOG.md, or a released skill version.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!--VITE PLUS START-->Using Vite+, the Unified Toolchain for the Web
This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called vp. Vite+ is distinct from Vite, and it invokes Vite through vp dev and vp build. Run vp help to print a list of commands and vp <command> --help for information about a specific command.
Docs are local at node_modules/vite-plus/docs or online at https://viteplus.dev/guide/.
Review Checklist
- Run
vp installafter pulling remote changes and before getting started. - Run
vp checkandvp testto format, lint, type check and test changes. - Check if there are
vite.config.tstasks orpackage.jsonscripts necessary for validation, run viavp run <script>. - If setup, runtime, or package-manager behavior looks wrong, run
vp env doctorand include its output when asking for help.
<!--VITE PLUS END-->Toolchain
vp and vpx replace the whole npm/pnpm/yarn/bun surface, one-off package runners included. Translate before
running anything:
| Instead of | Use |
npm install, pnpm install, yarn, bun install | vp install |
npm install <pkg>, pnpm add, yarn add, bun add | vp add <pkg> |
npm run <task>, pnpm run, yarn <task>, bun run | vp run <task> |
npx <pkg>, pnpm dlx, yarn dlx, bunx | vpx <pkg> (= vp dlx) |
npm exec, pnpm exec, yarn exec | vpx <bin> (= vp exec) |
vpx resolves a local binary first and downloads only if it is missing, so it covers both of the last two rows.
Reaching past them fails in different ways, which is why the rule is "always translate" rather than "watch for errors":
devEngines.packageManager pins this repo to pnpm, so npm and npx abort outright with EBADDEVENGINES, while yarn and
bun would ignore pnpm-workspace.yaml and pnpm-lock.yaml and quietly resolve a different dependency tree.
The npx in the README install snippets is what consumers type in their own projects — leave it alone.
Everything above the VITE PLUS END marker is generated. Edits there are overwritten; put repo-specific rules here.
Where this file lives
This is .claude/CLAUDE.md, not a root CLAUDE.md, on purpose. The repo root is the plugin root, and claude plugin
validate --strict fails on a CLAUDE.md there, because a plugin cannot ship project context that way. Claude Code
loads this path as project instructions all the same. Do not move it to the root.
Authoring skills
Skills live at skills/<bucket>/<name>/SKILL.md and are published for other people's projects, so the default is to
name no language, test runner, package manager, or directory layout. State the discipline; defer every tool decision
to the consuming project. This holds even when a rewriting or linting pass suggests otherwise — those optimize for
predictability, and none of them protect portability.
A skill genuinely about one stack is fine. It lists what it takes for granted under metadata.assumes in its
frontmatter — comma-separated, and metadata because that is where the Agent Skills spec puts fields it does not
define. Listed names stop counting as leaks in tests/skills.test.ts; unlisted ones still fail, and the description
has to name each one, since the description is what sends anyone to the skill — the agent when it is model-invoked, a
person reading the slash-command list when it is not. Prefer the version that assumes nothing where one exists — the
list is for skills that would be worse written portably, not a shortcut when portable is harder to write.
A skill is model-invoked by default. disable-model-invocation: true makes it user-invoked: it leaves the list the
harness injects, so neither the agent nor another skill can start it, and its description becomes a one-line summary
for the person reading the slash-command list rather than a trigger list for the agent. Use it when a misfire costs
more than the catch is worth — a skill that changes how the rest of the session runs, or spends it on a repo-wide
sweep.
The flag is a Claude Code field, so it does nothing under another harness. Say it in the body too, where every harness reads it: a user-invoked skill opens with "The user starts it, never you.", the reason a misfire is expensive, and an instruction to stand down if the agent arrived on its own judgment. See "Adding a skill" for why the repo carries no per-harness equivalent.
A skill ships only if its path appears in the skills array of .claude-plugin/plugin.json. Leaving it out fails
silently: the skill stays in the repo and simply never reaches plugin users. It must also get a row in the README
skills table, or nobody browsing the repo finds it. Both are covered by tests/skills.test.ts, so run the tests.
This repo publishes no marketplace of its own. The plugin is listed in the standalone catalogue at
iangregsondev/claude-marketplace, which reads plugin.json from here —
so plugin.json is the only manifest this repo owns, and nothing here needs updating when the catalogue changes.
Versioning
Skills version independently, through changesets, and nothing about a version is ever hand-edited.
- A new skill starts at
0.0.0, and its first changeset ismajor— that yields1.0.0, a release version rather than0.1.0. Writing1.0.0into the new manifest by hand skips a version and is wrong even though nothing fails. - Every skill change needs a changeset, keyed by the skill's directory name. Without one the change ships no bump.
- Never touch the
versionin.claude-plugin/plugin.json, a skill'sCHANGELOG.md, or a released skill version. The release workflow writes all three.
CONTRIBUTING.md is the full account of this repo's rules — the manifest-as-cache-key reasoning, the unscoped package names, the release and dry-run tasks. Read it before changing anything about how skills are packaged or released; this file only carries the parts that are easiest to walk past.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

