From vigiles
Converts hand-written CLAUDE.md or AGENTS.md files to typed .spec.ts specs using vigiles. Parses commands, key files, rules; classifies enforcements/guidance; verifies compilation for incremental adoption.
npx claudepluginhub zernie/vigilesThis skill uses the workspace's default tool permissions.
Convert an existing hand-written CLAUDE.md (or AGENTS.md) into a typed `CLAUDE.md.spec.ts` file. This is the incremental adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
Provides best practices for creating, updating, and auditing CLAUDE.md files including constraints, commands, architecture overviews, and bloat reduction for projects.
Improves CLAUDE.md files by wrapping conditional instructions in <important if> blocks to counter irrelevance warnings and boost adherence in Claude Code.
Guides Payload CMS config (payload.config.ts), collections, fields, hooks, access control, APIs. Debugs validation errors, security, relationships, queries, transactions, hook behavior.
Share bugs, ideas, or general feedback.
Convert an existing hand-written CLAUDE.md (or AGENTS.md) into a typed CLAUDE.md.spec.ts file. This is the incremental adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
Read the target instruction file (default: CLAUDE.md in the repo root). If the user specified a path, use that.
Also check if vigiles is installed: look for vigiles in package.json devDependencies. If not, suggest:
npm install -D vigiles
Identify these sections in the markdown:
`npm run build` — description or - `command` — description`src/foo.ts` — description listing important files### headings with **Enforced by:** or **Guidance only** annotationsFor each rule, classify it:
**Enforced by:** \linter/rule`→enforce("linter/rule", "why")`**Enforced by:** \code-review`or similar non-linter →guidance("...")`**Guidance only** → guidance("...")Create CLAUDE.md.spec.ts (or the appropriate name based on the source file) with this structure:
import {
claude,
enforce,
guidance,
check,
every,
file,
cmd,
ref,
instructions,
} from "vigiles/spec";
export default claude({
sections: {
// Prose sections here
},
keyFiles: {
// Key files here
},
commands: {
// Commands here
},
rules: {
// Rules here
},
});
Important guidelines:
file() refs in sections where file paths appear in backticks — this enables stale reference detectioncmd() refs for any npm run commands mentioned in sections**Enforced by:** \code-review`rules toguidance()` — code review is not a mechanical enforcement// TODO: classify as enforce() or guidance() comment**Why:** text as the second argument to enforce() or guidance()ref() for cross-referencesRun:
npm run build
npx vigiles compile CLAUDE.md.spec.ts
Compare the compiled output against the original file. Key differences are expected (formatting, section ordering), but all rules, commands, key files, and prose content should be preserved.
Show the user:
npx vigiles compilenpx vigiles checkAsk if they want you to write the file. If yes, also suggest adding to .gitignore or updating CI to run vigiles compile and vigiles check.
If the user wants CI integration, suggest adding to their GitHub Actions workflow:
- name: Compile specs
run: npx vigiles compile
- name: Verify integrity
run: npx vigiles check
Or using the vigiles GitHub Action:
- uses: zernie/vigiles@main
with:
command: check