Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
62 lines (42 loc) · 4.03 KB

CONTRIBUTING.md

File metadata and controls

62 lines (42 loc) · 4.03 KB
Raw

Contributing to Intelligentium

Intelligentium is an APM marketplace: a collection of plugins/<name>/ packages, each bundling one or more Copilot skills, published for install via apm install <plugin>@intelligentium.

Prerequisites

  • APM CLI (apm)
  • Node.js 20+ and npm install (only needed for the ARD catalog generator script)

Repository Layout

apm.yml                  # root manifest; marketplace.packages lists every plugin
plugins/<name>/
  apm.yml                # plugin manifest (name, version, tags, targets, deps)
  .apm/skills/<skill>/
    SKILL.md              # skill frontmatter (name, description) + body
    references/*.md       # optional deep-dive reference files

Master copies of skills live in .agents/skills/ at the repo root (used by this workspace's own Copilot). Plugins contain copies of a themed subset of those skills for publishing — keep both in sync when editing a skill that's shared.

Adding a Skill to an Existing Plugin

  1. Add plugins/<plugin>/.apm/skills/<skill-name>/SKILL.md with name/description frontmatter and the skill body. Add any references/*.md files it links to. Double-quote the description value (description: "...") — trigger-phrase descriptions contain colons that break strict YAML parsers when left unquoted.
  2. If the skill also exists as a master copy, mirror the change in .agents/skills/<skill-name>/.
  3. Add a row for the skill in plugins/<plugin>/README.md's skills table.
  4. Regenerate build artifacts (see Verifying Changes).

Adding a New Plugin Package

  1. Scaffold it: apm plugin init <name>. This creates a nested <name>/<name>/ — flatten it: mv "<name>/<name>"/* "<name>/" (or run apm plugin init from inside plugins/ and flatten there).
  2. Delete any generated plugin.json — apm pack synthesizes it from apm.yml, don't hand-author it.
  3. Fill in plugins/<name>/apm.yml (description, keywords, targets) and add the skill(s) under .apm/skills/.
  4. Register the package in the root apm.yml's marketplace.packages list (name, description, source: ./plugins/<name>, version, tags).
  5. Add a row for it in the README.md plugin table.
  6. Add plugins/<name>/README.md (name, description, a table of its skills linking to .apm/skills/<skill>, and the apm install <name>@intelligentium command). Every plugin must have one — keep its skills table in sync whenever a skill is added, removed, or renamed.
  7. Regenerate build artifacts (see Verifying Changes).

Verifying Changes

Run before opening a PR:

apm pack                  # rebuilds .claude-plugin/marketplace.json from apm.yml

apm compile only processes instructions/prompts/agents, not skills — for skill-only plugins it reports "No instruction files found," which is expected, not an error.

Commit the regenerated .claude-plugin/marketplace.json — it's consumed directly from the repo (by apm marketplace add), not built at install time.

.well-known/ai-catalog.json (the ARD catalog) does not need to be regenerated by hand: .github/workflows/ard-catalog.yml runs npm run generate:ard and auto-commits the result on push to main and on same-repo PR branches. Only forked PRs need a manual npm run generate:ard + commit, since CI can't push to a fork.

Releasing a Plugin

Bump the package's version in both root apm.yml and plugins/<name>/apm.yml. Once merged to main, .github/workflows/plugin-releases.yml creates the annotated tag (<name>-v<version>, per tag_pattern), creates the GitHub Release, and regenerates the website with that tag's release date. No manual tagging or release-date editing is needed.

Pull Requests

  • Keep the title a short, imperative summary (e.g. "Add math-foundations plugin").
  • One logical change per PR (a new plugin, a skill fix, a tooling change).
  • Re-run the commands in Verifying Changes and commit any resulting diffs.