Validate the skill graph once, then ship self-contained skills, a visual catalog, portable hooks, and exact manifests for every supported agent host. Deterministic output keeps local builds and CI aligned.
npm install --save-dev --save-exact @fam-tung-lam/ptlam-agent-plugin-compilerOne exact version in the lockfile, so CI compiles with the compiler you did.
The authored plugin manifest and skill sources are validated and compiled through one deterministic write plan into self-contained skills and exact provider manifest files.
Every compile walks these stages in order, and stops at the first one that cannot prove its result.
01model
Give dependencies, visibility, status, migration guidance, and manual-only invocation one source of truth in plugin/plugin.yml.
02validate
Validate schema, source layout, Markdown links, lifecycle rules, and recursive dependencies before any generated path changes.
03package
Compile each public root with generated frontmatter, dependency instructions, supporting files, and every required skill nested recursively.
04catalog
Generate an installable-skill table and Mermaid dependency graph, grouped by category and labelled with lifecycle status and visibility.
05translate
Emit exact manifests and translate portable hooks only where Claude, Codex, Copilot, Gemini, or Kimi exposes equivalent native events.
06verify
Write bounded output with atomic file and tree operations, verify it from disk, and use read-only check to fail CI on deterministic drift.
Select any combination in plugin/plugin.yml, or override the selection for a single run. Each adapter declares the exact manifest files it owns, and receives portable hooks only where the host exposes an equivalent native event.
Claude pluginclaude
.claude-plugin/plugin.json.claude-plugin/marketplace.jsonCodex plugincodex
.codex-plugin/plugin.jsonGitHub Copilot CLIcopilot
plugin.jsonGemini CLI extensiongemini
gemini-extension.jsonKimi Code CLI pluginkimi
kimi.plugin.json The shared skills/** tree is generated either way, so a plugin that targets no host manifest still gets self-contained skills. Node.js callers can register an adapter for a host the compiler does not ship — see Providers.
The package installs one executable, plugin-compiler. Run it through npm exec -- in a repository that has the package installed.
init writes missing source paths
Create a safe starter
validatereads only
Validate manifest, skills, hooks, and graph
compile writes managed output
Compile and verify managed output
checkreads only
Report generated drift
Every command takes --root, and validate, compile, and check take one provider selection — see the CLI reference.
The same authored source always compiles to the same bytes, and the compiler declares exactly which paths it owns. So it can compare the committed output with what the source implies.
$ npm exec -- plugin-compiler check Output check found 1 drift entry: - skills/prepare-change-plan/SKILL.md: content-differs
check writes nothing, names every path that drifted, and exits non-zero. No extra scripting is needed to fail a job.
Exit codes
012Wire it into a workflow with Continuous integration.