agent-skills-toolkit

Start, grow, govern, and level up an advanced cross-agent plugin over its whole lifecycle - climbing a Bronze / Silver / Gold standard, with a portable gate that proves the climb. For Claude Code and Codex.

Most skill collections are a flat, single-agent, ungoverned pile. This is the Standard that defines what a best-in-class, multi-agent skill library actually is, plus the portable tooling that authors components, grades a plugin against the Standard, and emits each component in the right format for each agent. The repository is built to its own Standard and self-validates at Gold in CI: it is meant to be the proof.

• Install
• What it is
• Use it
• What makes it different
• The tier model
• The catalog
• Find your way in
• Documentation
• Status
• Terminology
• Repository map

Install

Two install paths, for two different things: the full plugin (skills, subagents, commands) for an agent to run, or just the gate as an ordinary command-line tool with no agent involved.

As a Claude Code / Codex plugin - skills, subagents, and commands, driven by an agent:

# Add the marketplace once (by repo path)
/plugin marketplace add product-on-purpose/agent-plugins

# Install the toolkit (by marketplace identity)
/plugin install agent-skills-toolkit@product-on-purpose

You add the marketplace by its repo path and install by the marketplace identity (@product-on-purpose): the path is the address, the identity is the brand. The toolkit installs on Claude Code and Codex (it ships both native manifests). New here? Read What it is first, then Use it.

As a standalone gate - the deterministic CLI only, via npm, with no agent runtime required:

npx agent-skills-toolkit /path/to/your-plugin   # one-shot, grades the given path and exits with its code
npm install --save-dev agent-skills-toolkit     # or add it to your own toolchain / CI

npx agent-skills-toolkit (or agent-skills-toolkit once installed) runs check by default, so a bare path is enough to get a tier back; evaluate and tier-report are also available as subcommands. There is no askit bin alias - that name belongs to an unrelated package already on the npm registry. The npm package ships the gate and STANDARD.md only, not the askit-* authoring skills or the maintainer-only eval-run tooling; see Install and run via npm for the full command reference and exactly what is and is not included.

What it is

agent-skills-toolkit is two things working together, built for the whole life of a plugin - not just the moment you write a skill.

• The Advanced Skill Library Standard - a normative (RFC-2119) definition of what a best-in-class, multi-agent skill library is: components, conformance tiers, manifest, CI, and lifecycle. It is the bar you climb.
• The toolkit - skills, subagents, and portable Node validators that author every component type, grade a plugin against the Standard, and emit each component in the right format for each target agent (Claude Code and Codex). The validators run anywhere Node 22.12+ does, with a YAML parser as their only runtime dependency.

This is more than a skill builder. A single skill is where you start; the real work is starting, growing, governing, and leveling up a coherent, versioned plugin that works across more than one agent and holds together as it scales.

• Start - write your first skill, or scaffold a plugin from scratch: askit-build-skill, askit-init-plugin, askit-init-marketplace, or askit-migrate for an existing repo.
• Grow - add subagents, slash commands, MCP servers, hooks, workflows, chain contracts, output styles, status lines, and settings, through the askit-build-* family (emitted per agent).
• Govern - run the plugin over its lifetime: backlog with a why-gate, MADR decision records, releases, deprecations, templates, docs, and eval samples.
• Level up - climb Bronze to Silver to Gold by adding the machinery each tier certifies; a deterministic tier report names exactly what blocks the next rung.

The path is a flat pile of skills becoming a coherent, versioned plugin that conforms to a defined quality bar and works across more than one agent - and then keeps earning higher grades as it matures: loose components into a plugin into a skill library.

What it is, and is not:

• A lifecycle toolkit (start, grow, govern, level up a plugin), not a one-shot skill scaffolder.
• A deterministic gate that grades a whole library at once and reports the tier it earns, not a per-skill linter or style guide.
• Cross-agent from one canonical library.json emitted per agent (Claude Code and Codex), not a single-agent or Claude-only format.
• Self-proving (the repository validates itself against the Standard in CI), not an aspirational spec with no reference implementation.
• A grade a plugin earns (Bronze / Silver / Gold), not a separate artifact you install.

flowchart LR
    L["Loose components<br/>flat, single-agent, ungoverned"]
    B["Bronze (Universal)<br/>identical files, any agentskills.io agent"]
    S["Silver (Convergent)<br/>per-agent emission:<br/>subagents, commands, workflows"]
    G["Gold (Advanced)<br/>hooks, self-hosting CI, lifecycle,<br/>self-validating"]
    L --> B --> S --> G
    classDef bronze fill:#f3e9dc,stroke:#a97142,color:#111;
    classDef silver fill:#eceff1,stroke:#7c8a93,color:#111;
    classDef gold fill:#fff6da,stroke:#caa12a,color:#111;
    class B bronze;
    class S silver;
    class G gold;

Two ways in, one ladder

The same tier ladder serves two audiences, and you can self-locate on it.

• The beginner on-ramp. Build your first agentskills.io skill, then scaffold it into a plugin that parses, self-describes, and runs unchanged on any compliant agent. The smallest commitment that turns a pile of skills into a gradeable, portable plugin: Bronze.
• The advanced maintainer track. Take a real multi-component plugin cross-agent with verified format parity, then make it self-proving with hooks, regression-covered chains, self-hosting CI, and a disciplined release and deprecation story: Silver, then Gold.

Because the tiers are monotonic, the beginner's first Bronze plugin is the exact foundation the advanced track builds on. Nobody starts over. The bar rises and the earlier work still counts.

Use it

No setup. Install the plugin and drive it through skills:

• Grade a plugin - invoke askit-evaluate (or /askit-evaluate, or just ask "grade this plugin against the Standard"). You get the tier it earns, the burndown to the next one, and per-rule remediation.
• Start, build, adopt, govern - askit-init-plugin scaffolds a new plugin, the askit-build-* family adds any component conformant by construction, askit-migrate brings an existing repo up to the bar, and askit-backlog / askit-decision / askit-release / askit-deprecate run it over its lifetime.

The grade is trustworthy because it is deterministic: every skill runs the same model-free gate that also runs in CI, so a plugin proves itself instead of taking an agent's word for it (see What makes it different).

The loop the skills drive is the same at every tier: create a component conformant by construction, evaluate it against the Standard, improve what the burndown names, and repeat until the tier is earned.

flowchart LR
  C["Create<br/>askit-build-* (conformant by construction)"]
  E["Evaluate<br/>node scripts/check.mjs and askit-evaluate"]
  I["Improve<br/>fix what the burndown names"]
  C --> E --> I
  I --> E

What makes it different

Cross-agent emission is increasingly common. The defensible, less-occupied position is grading a whole library, deterministically, against a tier you can climb and verify. The gate is a portable pipeline: the plugin on disk feeds one check module per requirement, each emits findings, and they roll up to the tier earned plus the burndown to the next.

flowchart LR
  P["Plugin on disk<br/>library.json plus components"]
  C["Check modules<br/>one per reqId (U, S, G)"]
  F["Findings<br/>error or warn"]
  T["tier-report<br/>tier earned plus burndown"]
  P --> C --> F --> T

The differentiators:

• Library-level, not per-unit. The gate grades the entire plugin - manifest, components, cross-agent emission, CI, and lifecycle - not one skill in isolation. The unit of governance is the library.
• Deterministic, not vibes. A portable Node gate with real exit codes, not an LLM opinion. Judgment-based evaluation (behavioral and qualitative) exists too, but it sits beside the gate as opt-in evidence and never decides a pass or fail.
• Tiered and climbable. Bronze, Silver, Gold are monotonic: each includes everything below it. The tier report hands back a burndown that names exactly what blocks the next tier, so the climb is a worklist, not a guess.
• Cross-agent by construction. One authored library.json is the single source of truth; the native per-agent manifests are generated from it, so Claude Code and Codex stay in lockstep.
• Self-proving. The repository is the Gold-grade reference implementation of its own Standard, and it runs that Standard against itself in CI.

The deterministic boundary is the load-bearing idea: a plugin's structure runs through the model-free gate, which decides pass or fail; its quality (does a skill trigger, is the output good) runs through askit-evaluate, which sits beside the gate as opt-in evidence and never decides the grade.

flowchart TD
  S["Structure<br/>manifest, anatomy, emission, CI"]
  G["Deterministic gate<br/>node scripts/check.mjs"]
  V["Pass or fail<br/>real exit code, runs in CI"]
  Q["Quality<br/>triggering and output"]
  E["askit-evaluate<br/>behavioral plus review, opt-in"]
  N["Evidence beside the gate<br/>never decides the grade"]
  S --> G --> V
  Q --> E --> N

How it compares

Most tools grade one skill or plugin in isolation; the less-occupied position is grading a whole library on a climbable tier with a deterministic gate. A dated snapshot of the differentiators (verified 2026-06-10 against each tool's primary sources; full table, all ten tools, and per-cell citations in the comparison):

No single dimension is uniquely ours; the unoccupied position is the combination (whole-library, tiered, deterministic, cross-agent, self-proving, plus a provenance split no other tool has). See the full comparison and how it was verified.

The tier model

A bare folder of agentskills.io skills is just loose components: the skills work a la carte, but the collection is not yet a plugin. The three tiers are the ladder that turns it into a best-in-class library, one rung at a time. They are monotonic - each tier includes everything below it - so a Bronze plugin grows into Silver and Gold without rework. The bar rises, and the earlier work still counts.

A tier is reported only when its checks actually pass; the tooling flags any claim above what is met. The spine is 34 checks total (U1-U9, U11-U17, S1-S8, G1-G10); the G7 slot is the docs-frontmatter check (assigned in Standard v0.10), U13 (skill-registration) was added in Standard v0.12, and U14 (agent-restricted-fields) in Standard v0.13. Tier inclusion (a Gold plugin satisfies every Bronze and Silver requirement) is a structural property of the monotonic tiers, not a numbered check.

At a glance

Three rungs, monotonic - each includes everything below it (per-tier detail follows):

• Bronze - Universal (U1-U9, U11-U13, 12 checks). Certifies identical, portable files that run unchanged on any agentskills.io agent. For the beginner on-ramp. Adds a minimal library.json, valid skill anatomy, and a description that clears the bar.
• Silver - Convergent (+ S1-S8, 19). Certifies the multi-agent machinery emitted in the right format for every target agent. For real multi-component plugins on both Claude and Codex. Adds subagents, commands, workflows, chain contracts, per-agent emission, and semver governance.
• Gold - Advanced (+ G1-G10, 29). Certifies that the plugin proves itself: deep lifecycle plus self-hosting CI. For maintainers running plugins at scale. Adds hooks, self-hosting CI, regression-covered chains, drift-checked generated docs, and a release and deprecation policy.

Read it as a climb. Bronze makes a plugin portable. Silver makes it genuinely cross-agent. Gold makes it self-proving. Each rung is the floor the next one builds on.

Bronze - Universal - the start line

Certifies: the plugin parses and self-describes with portable, agent-agnostic files that run unchanged on any agentskills.io-compliant agent.

• For: beginners and first-time authors. The smallest commitment that makes a pile of skills a real plugin.
• Requires (U1-U9, U11-U13):
  • U1 - a minimal library.json carrying at least name, version, and tier
  • U2-U4 - valid agentskills.io skill anatomy and frontmatter, with each skill's name equal to its directory; a root AGENTS.md entrypoint is part of the required anatomy
  • U5 - a description that clears the what-plus-when-plus-trigger quality bar
  • U6-U7 - reference links that resolve, and an instruction-budget warning so context stays scarce
  • U8-U9 - native-manifest agreement, and package.json / library.json version agreement
  • U11-U13 - well-formed MCP entries that commit no secrets, structurally valid mermaid blocks, and every shipped skill registered in the manifest
• Why it matters: the manifest (U1) is the line between a reusable folder and a release unit that carries a version, so tooling can grade and version it. The description bar protects the one signal an agent uses to decide relevance; the reference-link and budget rules keep context scarce and progressively disclosed, which is how frontier models actually follow instructions.
• Payoff: a Bronze plugin is installable and behaves the same on Claude Code, Codex, and the broader agentskills.io ecosystem at once. Write once, run anywhere.

Silver - Convergent - the multi-agent rung

Certifies: the plugin adds the multi-agent machinery - subagents, commands, workflows, chain contracts - emitted in the correct format for every agent it targets.

• For: real multi-component plugins that need to compose safely and ship to more than one agent.
• Requires (+ S1-S8):
  • S1-S2 - declared agent-targets and a short component prefix carried by every component
  • S3, S8 - a components index that mirrors what is on disk, in both directions
  • S4-S5 - valid chain contracts in agents/_chain-permitted.yaml with no orphans or phantoms, and workflow steps that reference skills that exist
  • S6-S7 - per-target emission, with a native manifest and a command contract present for each declared target
  • plus governance stepping up: per-component HISTORY.md, a CHANGELOG, and semver throughout
• Why it matters: Claude and Codex support the same concepts in different file formats, so a single file cannot serve both - per-target emission (S6) is what keeps a plugin genuinely cross-agent instead of secretly Claude-only. The prefix (S2) stops generic names like init from colliding on agents that lack plugin namespacing. The index mirroring disk (S3, S8) keeps the manifest honest as the single source of truth, and chain contracts (S4) make inter-component calls explicit and safe.
• Payoff: a Silver plugin delivers the same intent across Claude and Codex with verified format parity and collision-proof names.

Gold - Advanced - the self-proving summit

Certifies: the self-proving bar - deep lifecycle capability plus CI that validates the plugin against this Standard and passes.

• For: maintainers running plugins at scale who need lifecycle guarantees: documented hooks, regression-protected chains, drift-free generated docs, and a disciplined release and deprecation story.
• Requires (+ G1-G10):
  • G1 - every hook documents its event, trigger, matcher, scope, and failure behavior
  • G2 - the plugin ships self-hosting CI that runs the full tier-applicable gate and passes it
  • G3 - each chain edge and hook carries at least one eval or regression case CI executes, so changing one component cannot silently break a consumer
  • G4 - INDEX.md and the native manifests are generated from the authored sources and drift-checked, so a hand-edited generated file is an error
  • G5 - a curated RELEASE-NOTES.md distinct from CHANGELOG.md
  • G6 - a deprecation policy with status / deprecated-by / remove-in that tooling recognizes
  • G7 - every published docs/** page carries the frontmatter taxonomy (title, description, audience, level; sec 8.4)
  • G8 - every meaningful folder's README.md inventory set-equals its actual immediate children
  • G9 - every hand-authored source file carries a four-field header docblock (what it is / what it does / why / what uses it)
  • G10 - the Diataxis quadrants are non-empty, every ADR carries a ## TL;DR, and the architecture overview links its detailed page
• Why it matters: self-hosting CI (G2) closes the credibility loop - a Standard whose own reference plugin cannot pass its validators is not trustworthy, so the prover must be the proof. Regression coverage (G3) turns "changing X broke Y" from a surprise into a CI failure. Generating INDEX and the manifests from one authored source (G4) keeps the agent view and the human view from drifting apart at scale.
• Payoff: a Gold plugin is a maintainable, best-in-class library that demonstrably conforms to the Standard. It is the tier this toolkit itself declares (tier: advanced) and passes against itself, with an empty blocked list as the proof.

Locate yourself

• Loose skills, or none yet -> Bronze. Use askit-build-skill, askit-init-plugin, or askit-migrate.
• A Bronze plugin you want on both agents -> Silver. Use the askit-build-* family, then askit-evaluate (or node scripts/check.mjs) for the burndown.
• A Silver plugin you want self-proving -> Gold. Use askit-build-hook, askit-release, askit-deprecate, plus self-hosting CI.

Invoke askit-evaluate (or run node scripts/check.mjs) at any point to see the highest tier you satisfy and exactly what blocks the next one.

The catalog

26 skills, 7 subagents, 2 commands on disk. Skills carry the askit- prefix and emit for both agents unless a one-liner notes a Claude-only output; subagents and commands are Claude-only. Full per-component reference lives in docs/reference/ and on the live docs site; INDEX.md is the generated map.

Authoring (11)

The askit-build-* family scaffolds and improves each component type to the Standard.

• askit-build-skill - author or improve an agentskills.io SKILL.md, scaffold a skill directory, and raise its conformance and description quality.
• askit-build-subagent - create or improve a Claude subagent in agents/<name>.md, declaring tools and chain (Claude-only).
• askit-build-command - create or improve a Claude slash command that maps to a skill, giving it an explicit /command entry point.
• askit-build-mcp - author or extend a portable .mcp.json server definition and wire the per-target mcpServers manifest pointer.
• askit-build-hook - add Advanced-tier event-driven hooks that guard tool or session events, inject context, and document failure behavior.
• askit-build-chain-contract - declare permitted inter-component invocations in agents/_chain-permitted.yaml; resolves S4 orphan or phantom findings.
• askit-build-agents-md - author or sync AGENTS.md, the agent navigation entrypoint, aligning it with the component index.
• askit-build-output-style - author or improve a Claude Code output style defining a response mode (Claude-only).
• askit-build-workflow - formalize a recurring multi-skill sequence as a _workflows file with ordered steps and exit criteria; resolves S5 findings.
• askit-build-statusline - author a Claude Code status line script and wire its settings registration (Claude-only).
• askit-build-settings - author per-target settings and permissions, scope least-privilege allowlists, wire env vars, and register hooks.

Assessment (1)

Evaluating a skill or plugin against the Standard for conformance, behavior, and quality.

• askit-evaluate - audit a skill or plugin against the Standard in three modes: deterministic conformance plus tier, behavioral pass, and qualitative review.

Docs and samples (2)

Authoring documentation and the sample/eval sets that prove a skill behaves and triggers correctly.

• askit-build-docs - author or refresh docs across modes (readme, tutorial, reference, faq, and more) and stand up an Astro Starlight docs site.
• askit-build-samples - create and validate a skill's golden examples, anti-examples, and triggering cases, and detect drift against current behavior.

Governance and lifecycle (6)

Managing backlogs, decisions, releases, deprecations, templates, and the upstream spec this Standard tracks over a plugin's lifetime.

• askit-backlog - capture new-component proposals through the why-gate, prioritize backlog items, and prune stale or completed enhancements.
• askit-decision - record MADR architecture decision records and RFCs in docs/internal, plus the TL;DR companion for long decision docs.
• askit-release - cut a release: compute the version, promote the changelog, curate release notes, and run the readiness gate.
• askit-deprecate - record a component's deprecation (status, replacement, removal target) and keep it validating until removal.
• askit-template-manager - add or update the global templates directory and keep templates in sync with the shapes the scaffolders produce.
• askit-standards-watch - check whether the pinned agentskills.io upstream spec has moved, map each change to the Universal checks it lands on, and draft the proposal ADR (it proposes; it never amends a check or the Standard).

Onboarding and adoption (4)

Starting new plugins and marketplaces, migrating existing repos, and advising on targets and tier.

• askit-init-plugin - scaffold a new Bronze-anatomy plugin from scratch and onboard the maintainer via interview, questionnaire, or hybrid mode.
• askit-init-marketplace - stand up or validate a marketplace index that catalogs plugins, checking each entry, plugin reference, and version.
• askit-migrate - assess an existing skills repo against the Standard, write the minimal manifest, and produce a staged bring-to-conformance plan.
• askit-capability-advisor - report which component types a target agent can run and recommend a conformance tier before a plugin is built.

Subagents (7, Claude-only)

The bounded delegate roles the toolkit's skills invoke; each is Claude-only and cannot ship to Codex.

• askit-skill-author - author and improve agentskills.io skills to the Standard; the bounded delegate behind askit-build-skill.
• askit-evaluator - assess a skill or plugin against the Standard and report findings with remediation; the read-only role behind askit-evaluate.
• askit-reviewer - review a component or change for correctness, conformance, and quality, reporting findings with severity.
• askit-quality-grader - run a skill against its eval-set and grade the outputs; the opt-in LLM-judge behind askit-evaluate's behavioral mode.
• askit-explorer - survey a repository broadly and report a structural map of its components and layout.
• askit-file-search - locate specific files, symbols, or text and report matching paths and lines.
• askit-file-ops - apply a specified set of file create and edit operations precisely; the bounded mutation role for authoring.

Commands (2, Claude-only)

The Claude slash commands that give the core flows an explicit /command entry point.

• /askit-evaluate - invoke the askit-evaluate skill to report per-rule findings, the tier, and remediation for a path.
• /askit-build-skill - invoke the askit-build-skill skill to scaffold a new SKILL.md or raise an existing skill's conformance.

Find your way in

• Not sure any of this is worth it - Why a standard, and what it delivers. The case, the outcomes, and what it deliberately does not do.
• Not sure what to read - Reading paths. Six guided routes, one per kind of reader.
• Understand what a best-in-class library is - STANDARD.md and The tier model.
• Grade a plugin you already have - the askit-evaluate skill, or node scripts/check.mjs for the burndown.
• Build your first skill - askit-build-skill (or the /askit-build-skill command).
• Start a brand-new plugin - askit-init-plugin.
• Bring an existing skills repo up to the Standard - askit-migrate.
• See whether your agent supports a component type - askit-capability-advisor.
• Read the full reference - docs/ and the live docs site.

Documentation

• Why a standard, and what it delivers - the case for grading against a written standard, the outcomes it produces, and who benefits. Written for technical and non-technical readers alike; start here if you have not already bought the premise.
• Reading paths - six guided routes through these docs, one per kind of reader, with what each resource is and why it matters.
• STANDARD.md - the normative Standard that every tool here enforces (component model, tiers, manifest schema, CI and release expectations, lifecycle).
• Live docs site - the published Diataxis docs (Astro Starlight, deployed to GitHub Pages).
• docs/ - tutorials, how-to guides, per-component reference, and explanation in-repo.
• INDEX.md - the generated human map of every component.
• AGENTS.md - the agent navigation entrypoint.

Status

v1.15.0, Gold grade, installable. The repository declares tier: advanced and self-validates at Advanced in CI: the full gate is green and tier-report prints advanced with an empty burndown, so the toolkit is a self-proving example of the Standard it defines. Gold check G1 (hooks) now grades the toolkit's own demonstrative no-dash PreToolUse hook; G6 (deprecation) is still satisfied without exercise, since the toolkit ships no deprecated components yet. The toolkit installs from the product-on-purpose marketplace (see Install).

• Version - 1.15.0 (Standard v0.15).
• Tier - Advanced (Gold), self-validated.
• Install - product-on-purpose marketplace (agent-plugins).
• Components - 26 skills, 7 subagents, 2 commands.
• Validation spine - 34 checks (U1-U9, U11-U17, S1-S8, G1-G10), graded against the Standard version a plugin PINS: a requirement introduced or tightened after your pin is surfaced as Standard debt, never a gate failure, until you adopt it.
• Evaluation scopes - 3: one plugin, one component, or a whole marketplace.json catalogue (marketplace scope).
• Agents - Claude Code and Codex; agentskills.io-compatible at Bronze.
• License - Apache-2.0.
• Docs site - product-on-purpose.github.io/agent-skills-toolkit.

The Phase 0 Bronze bootstrap is historical context (see docs/internal/BOOTSTRAP.md).

Terminology

The vocabulary is strict because two independent axes never mix.

• Structure (what a thing physically is): a component (the unit of reuse) sits inside a plugin (the unit of release, which carries the one version), which sits inside a workspace; a marketplace catalogs plugins for discovery and install.
• Quality (how good a plugin is): a skill library is the grade a plugin earns by conforming to this Standard (Bronze / Silver / Gold). It is a grade, not a separate artifact.

The path is loose components into a plugin into a skill library.

Repository map

• STANDARD.md - the normative Standard.
• INDEX.md - the generated map of the repository.
• AGENTS.md - the agent navigation entrypoint.
• scripts/ - the portable validation spine (check.mjs, tier-report.mjs; one runtime dependency, a YAML parser), the per-check modules, and the manifest and index generators.
• skills/, agents/, commands/ - the components.
• docs/ - tutorials, how-to, reference, and explanation; docs/internal/ holds the design record, decisions, and backlog.
• CHANGELOG.md - release history.

License

Apache-2.0. See LICENSE.

Built with purpose by Product on Purpose.