Maintainer Guide

May 10, 2026 ยท View on GitHub

This document is for repository maintenance, catalog governance, packaging, and release operations. The public landing page stays in the root README.md.

Repository Layout

  • skills/ is the source catalog.
  • plugins/ contains distributable plugin bundles.
  • adapters/ contains export templates for agent ecosystems.
  • docs/ contains user-facing and maintainer-facing documentation.
  • .claude-plugin/marketplace.json is the Claude Code marketplace manifest.
  • .agents/plugins/marketplace.json is the Codex marketplace manifest.

Operating Rules

  • Inspect the repository before editing.
  • Prefer the smallest reversible change.
  • Do not invent APIs, commands, or compatibility data.
  • Keep Angular upgrade hops separate from modernization work.
  • Do not add dependencies unless they are required for the task.
  • Preserve the separation between source skills in skills/ and distributable bundles in plugins/.

Core Validation Commands

npm run skills:validate
npm run skills:catalog
npm run plugins:sync
npm run consistency:validate
npm run marketplaces:validate
npm run skills:publish:pack
npm run publish:validate
npm run pack:dry

Workflow Intent

  • ci.yml regenerates the catalog and plugin bundles, checks drift, builds publish bundles, and validates those bundles.
  • release-gates.yml validates skills, plugin coverage, consistency, marketplaces, and package dry runs.
  • release.yml prepares release artifacts and only publishes to npm when manually dispatched with publish enabled.
  • Marketplace workflows validate the Claude Code and Codex manifests and the packaged plugin roots.

Documentation Boundaries

  • README.md is the public landing page.
  • docs/getting-started.md and docs/cli-reference.md are user-facing.
  • docs/release-checklist.md is the operational release checklist.
  • Keep deep maintainer detail out of the root README unless it directly helps first-time adoption.

Marketplace Notes

  • Keep the public docs aligned with the CLI behavior that is actually available.
  • Keep plugins/ generated from skills/ with npm run plugins:sync; every source skill must be present in at least one marketplace bundle.
  • Validate marketplace manifest structure directly for Codex.
  • Use claude plugin validate . when validating Claude marketplace behavior locally.
  • Do not claim direct publication to external marketplaces when the repo only prepares deterministic artifacts for upload.