agentleFS
iangregsondeviangregsondev/agent-skills/.claude/CLAUDE.md

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

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
  1. Distinctive:

    Every skill change needs a changeset, keyed by the skill's directory name.

    line 86
  2. Very specific:

    Never touch the version in .claude-plugin/plugin.json, a skill's CHANGELOG.md, or a released skill version.

    line 87

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md
<!--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 install after pulling remote changes and before getting started.
  • Run vp check and vp test to format, lint, type check and test changes.
  • Check if there are vite.config.ts tasks or package.json scripts necessary for validation, run via vp run <script>.
  • If setup, runtime, or package-manager behavior looks wrong, run vp env doctor and 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 ofUse
npm install, pnpm install, yarn, bun installvp install
npm install <pkg>, pnpm add, yarn add, bun addvp add <pkg>
npm run <task>, pnpm run, yarn <task>, bun runvp run <task>
npx <pkg>, pnpm dlx, yarn dlx, bunxvpx <pkg> (= vp dlx)
npm exec, pnpm exec, yarn execvpx <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 is major — that yields 1.0.0, a release version rather than 0.1.0. Writing 1.0.0 into 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 version in .claude-plugin/plugin.json, a skill's CHANGELOG.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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.