Skip to content

Give each skill its own APM package and version - #51

Open
CodyCBakerPhD wants to merge 11 commits into
masterfrom
claude/per-skill-apm-manifests
Open

CodyCBakerPhD wants to merge 11 commits into
masterfrom
claude/per-skill-apm-manifests

Conversation

@CodyCBakerPhD

@CodyCBakerPhD CodyCBakerPhD commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Consumers that install a skill with git: con/skills + skills: [...] (e.g. bbqs-web-app-template, nwb-benchmarks-dashboard) see con/skills 0.1.0 for every skill in apm.lock.yaml and apm deps list. That is the never-bumped root apm.yml. apm-cli 0.31.0 never reads a skill's frontmatter version: (primitives/parser.py parse_skill_file takes only name and description), so the commit SHA is the only real version a consumer has.

Change

  • Each skills/<name>/apm.yml (name + version) makes that skill its own APM package and is the only place its version lives. Five skills had a frontmatter version; their manifests start from it, and every other skill starts at 0.1.0. No version is bumped in this PR.
  • The frontmatter version: is removed from those five SKILL.md files. The skills that stamp their output (bot-pr-sweep's pr_gate.py, suggest-skill-fixes, the review-* conventions) now read the version from the apm.yml that APM deploys beside SKILL.md.
  • validate_skills.py fails on a missing or invalid manifest (E010) and on any frontmatter version: (E011).
  • The root apm.yml is removed. con/skills is a monorepo of independent skills, not a package to install as a whole. check_apm.py installs and restores each skill as a subdirectory package.
  • README, AGENTS.md, install-apm-skills, author-apm-skills and code-quality-report-conventions are updated.
  • Releasing needs no maintainer action beyond the version bump in the PR. Consumers pin a commit, and APM reads the skill's apm.yml at that commit. No tags are used.

Verified (apm-cli 0.31.0)

  • apm install con/skills/skills/<name>#<sha>: the lock records the skill's own name and version (bot-pr-sweep 0.6.0), and apm.yml is deployed next to SKILL.md.
  • Both consumer repos still pass apm install --frozen and apm audit --ci, since they pin a SHA.
  • tox -e validate,apm,security-static,security-deps and check_apm.py --source pass.

Consumers

Nothing changes until the next pin move. Then replace {git: con/skills, ref, skills: [...]} with one {git: con/skills, path: skills/<name>, ref: <sha>} per skill. Move pins by editing the SHA, not with apm update, which can resolve to the old bare tag 0.20261015.0.

Relation to #50

#50 no longer edits AGENTS.md, so the two can merge in either order. If this PR merges first, #50's setup-chromatic rework should bump skills/setup-chromatic/apm.yml to 0.2.0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu

Each skills/<name>/apm.yml declares the skill's name, version and
description, so APM can record a skill's own version. Skills with a
frontmatter version keep it; the rest start at 0.1.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu
Validate each skill's apm.yml and its agreement with a frontmatter
version (E010, E011), install each skill as its own package in the apm
check, list missing <name>--v<version> release tags, and document the
install form, versioning and tagging.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu
Separate calls leave target: legacy deployments in the lock, which the
frozen restore then rewrites. Tell consumers the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu
@CodyCBakerPhD CodyCBakerPhD self-assigned this Nov 20, 2026
CodyCBakerPhD pushed a commit that referenced this pull request Nov 20, 2026
This reverts commit 8a74a96. #51 rewrites the
AGENTS.md "Skill versions" section, which covers this sentence, so this pull request stays
limited to setup-chromatic.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw3QuYxA1bV48ZgQcor
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu
A consumer pinning a commit already gets the skill's version from its
apm.yml, so a merged version bump needs no release tags. Remove
ci/skill_tags.py and the Release tags section; note that semver refs
would need <name>--v<version> tags, which this repository does not
publish.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu

@yarikoptic-gitmate yarikoptic-gitmate left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @CodyCBakerPhD. Reviewed at 24ad45f (still a draft, so take this as early feedback). The approach holds up: the PR's claims about apm-cli 0.31.0 were checked against its source and by running it, and a per-skill apm.yml is the only way 0.31 records a per-skill version in the lock. CI is green, and tox -e validate,apm plus ci/check_apm.py --source con/skills#b4205e8… pass locally. Dropping the tagging procedure in 24ad45f made the PR leaner.

Inline, most important first:

  • Keep the root apm.yml. It coexists with the per-skill manifests, spares existing consumers a lock change, and removes text and a special case from this PR.
  • apm update moves a commit pin back to the bare tag 0.20261015.0, a commit where most skills do not exist. Not new, but commit pins are now the only documented form. Delete the tag or warn.
  • Two-line manifests: description and type: skill are not used by APM, and 21 of 25 descriptions already differ from their SKILL.md.
  • Bump rule: install-apm-skills and author-apm-skills change procedure here but stay at 0.1.0.
  • Three nits in ci/.

Outside the diff, text this PR makes stale:

  • skills/code-quality-report-conventions/SKILL.md:17 still gives the root form. In one call, as the PR recommends:
    apm install con/skills/skills/code-quality-report-conventions#<commit> con/skills/skills/review-repo-code-quality#<commit> [con/skills/skills/review-org-code-quality#<commit>]
  • Same file, line 25: "Bump version: here when…" now fails E011 if followed literally. Say apm.yml and here.
  • skills/code-quality-report-conventions/report-conventions.md:32: "an apm.lock.yaml with a con/skills entry" can now match several entries at different commits. It should name the entry whose virtual_path is skills/{skill name}. This one changes what a run does, so it is a PATCH bump of that skill.

Two questions, not requests:

  1. The version of the five stamping skills now lives in two files, with E011 and its test to keep them equal. APM deploys apm.yml beside SKILL.md, so those skills could read it from there and the frontmatter copy and E011 could go. The cost: an extra file read at run time, and a changed stamping step in five skills. Worth it?
  2. review-repo-code-quality and review-org-code-quality need code-quality-report-conventions at run time. A dependencies: entry in their apm.yml does resolve transitively for subdirectory packages of the same repository (run with a range against tags in a mirror). Without tags it would need a SHA that is bumped on every change, so probably not for this PR.

Not checked: the two consumer repositories named in the PR body.

This review went through two independent reviewer passes (APM packaging; Python/CI and skill authoring), and both agreed with the points above.


Generated by Claude Code

Comment thread apm.yml Resolved
Comment thread AGENTS.md Resolved
Comment thread skills/analyze-duplicates/apm.yml Resolved
Comment thread skills/install-apm-skills/apm.yml Resolved
Comment thread ci/tests/test_apm_manifest.py Resolved
Comment thread ci/validate_skills.py Resolved
Comment thread ci/check_apm.py Resolved
…rning

- Per-skill apm.yml keeps only name and version; APM needs no more,
  and the copied descriptions had already drifted.
- code-quality-report-conventions: subdirectory install command, bump
  both version copies, match the lock entry by virtual_path (0.2.1).
- AGENTS.md: versions start with this PR; frontmatter copy is unquoted;
  move pins by editing the SHA, since apm update and semver refs land
  on the old bare tag. Same warning in install-apm-skills.
- E011 compares values directly; drop the duplicate collection test and
  the single-use ignore_deployed helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Commit bf7ab39 addresses the inline points (replies are on each thread) plus the stale text outside the diff:

  • code-quality-report-conventions/SKILL.md now uses the one-call subdirectory install and says to bump apm.yml and the frontmatter together.
  • report-conventions.md now matches the lock entry by virtual_path: skills/{skill name}. That changes what a run does, so the skill moves to 0.2.1 in both places.

tox -e validate,apm,security-static,security-deps passes.

On your two questions:

  1. Reading apm.yml at run time: I'm keeping the frontmatter copy and E011 for now. Moving the stamp source changes the stamping step in five skills, and it only works where apm.yml gets deployed alongside SKILL.md. That fits better as its own PR.
  2. Transitive dependencies:: agreed, not in this PR. Without tags it would need a SHA that changes with every edit.

The root apm.yml decision is with the PR author (see that thread). The 0.20261015.0 tag is left to the maintainers.


Generated by Claude Code

Say that only individual skills are installed, and drop the
repository-root install check from the Git package check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu
Drop version: from the five SKILL.md frontmatters that carried it.
Skills that stamp their output read the version from the apm.yml
beside their SKILL.md (bot-pr-sweep's pr_gate.py, suggest-skill-fixes,
the review conventions). E011 now rejects a frontmatter version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu

Copy link
Copy Markdown
Contributor Author

Update on question 1. My earlier answer, which kept the frontmatter copy, is superseded. In 9a03178, at the PR author's request, apm.yml became the only place a skill's version lives. The five SKILL.md frontmatters no longer have a version:, and the stamping skills now read the version from the apm.yml beside SKILL.md (pr_gate.py plus its test, suggest-skill-fixes, report-conventions.md, review-org-code-quality). E011 now rejects any frontmatter version:. CI is green.


Generated by Claude Code

@yarikoptic-gitmate yarikoptic-gitmate left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed 9a03178 (bf7ab39, 6af9790, 9a03178). The first round's points are addressed, the root apm.yml decision is settled, and moving the version into apm.yml alone removes the two-file sync and reads better than what I reviewed before. Nothing blocking; one inconsistency worth fixing before merge and a few nits, all inline or below.

Worth fixing: code-quality-report-conventions is bumped to 0.2.1 while AGENTS.md says this PR bumps nothing (inline; the collision came from my first review).

What was checked this round, by two independent reviewer passes (APM packaging; Python/CI and skill authoring):

  • "APM deploys apm.yml beside SKILL.md", which the stamping skills now depend on, holds. Run with apm-cli 0.31.0:
    • Local path and Git subdirectory installs with --target agent-skills, and --target claude, all deploy apm.yml into the skill's directory, and the lock lists it in deployed_files.
    • pr_gate.skill_version() on a deployed copy returns 0.6.0.
    • check_deployed in ci/check_apm.py already compares deployed files with the source tree, so CI guards this without a new check.
  • Tests: tox -e validate,apm passes; ci/tests (13) and skills/bot-pr-sweep/tests (128) pass; ci/validate_skills.py reports 0 errors for 25 skills. CI is green.
  • Stale text: nothing in README, AGENTS.md, ci/, tox.ini, .github or skills/ still points at a frontmatter version:.
  • ci/check_apm.py: --source is still coherent after the root-form block went (.github/workflows/validate.yml passes it), and no unused code is left there.

Nits without a thread:

  • AGENTS.md line 141 is 103 characters; rewrap.
  • Optional: _VERSION in pr_gate.py returns unknown for version: "0.6.0" # comment, which E010 accepts. None of the 25 manifests has one and the failure is a visible unknown, so leaving it is fine; ending the pattern with \s*(?:#.*)?$ would cover it.
  • Optional: pr_gate.py falls back to unknown where report-conventions.md and suggest-skill-fixes say unversioned. That predates this PR.

I resolved the first round's threads, as each is addressed.

Not checked: the two consumer repositories named in the PR body.


Generated by Claude Code

Comment thread ci/tests/test_apm_manifest.py Resolved
Comment thread ci/validate_skills.py Resolved
Comment thread skills/suggest-skill-fixes/SKILL.md Resolved
- code-quality-report-conventions back to 0.2.0: this PR bumps nothing.
- Drop an unused variable in E010 and the description leftovers in its
  test; rewrap a long AGENTS.md line.
- suggest-skill-fixes: any skill without an apm.yml is unversioned.
- pr_gate.py accepts a trailing comment after the apm.yml version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu

Copy link
Copy Markdown
Contributor Author

Thanks for the re-review. Commit b93f166 addresses the inline threads and two of the nits without a thread:

  • I rewrapped AGENTS.md line 141.
  • pr_gate.py's _VERSION now accepts a trailing # comment. Its test covers that case.

I left one optional nit for a separate change. pr_gate.py prints unknown where the docs say unversioned; that predates this PR and would change bot-pr-sweep's report output.

tox -e validate,apm,security-static,security-deps passes.


Generated by Claude Code

@yarikoptic-gitmate yarikoptic-gitmate left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed b93f166. Everything from the second round is addressed and nothing blocking remains. One line-length nit is inline; take it or leave it.

What was checked this round, by two independent reviewer passes (APM packaging; Python/CI):

  • The commit does what it says: code-quality-report-conventions is back at 0.2.0, so every apm.yml version equals the frontmatter version on master and no SKILL.md carries a version:.
  • _VERSION in pr_gate.py, run against 34 inputs beside what E010 accepts:
    • It matches quoted, single-quoted and bare values, a trailing comment and CRLF.
    • It rejects an unterminated or mismatched quote, an indented version: and four-part or suffixed versions.
    • The two can disagree only on forms nobody writes in a two-line manifest (version : "1.2.3", a quoted key, a duplicate key), where the stamp would read unknown. No change needed.
  • check_apm_manifest: nothing reads version after E010, so the removal is right, and no other dead code is left there or in its test.
  • Tests: ci/validate_skills.py reports 0 errors for 25 skills; ci/tests (13) and skills/bot-pr-sweep/tests (128) pass. CI is green on b93f166.
  • Reuse: skill_version exists in both ci/check_apm.py and pr_gate.py, which is right, since the gate script is bundled and standard-library only.

Not run this round: tox -e apm against a real apm-cli (it ran in CI), and the two consumer repositories named in the PR body.

I resolved the second round's threads, as each is addressed. Leaving this as a comment, not an approval; merging is for a maintainer to decide.


Generated by Claude Code

Comment thread AGENTS.md Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu

@yarikoptic-gitmate yarikoptic-gitmate left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked 692c030: it only rewraps the long AGENTS.md line, and CI is green on it. Nothing further from this review; merging is for a maintainer to decide.


Generated by Claude Code

Resolve bot-pr-sweep's version conflict: #52 bumped it to 0.7.0 in the
SKILL.md frontmatter; here the version lives only in apm.yml, so it moves
there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw79etX6u2VyPivrDeu

Copy link
Copy Markdown
Contributor

Checked 097d4bd, the merge of master (#52) into this branch. The conflict is resolved the right way: bot-pr-sweep's 0.7.0 from #52 is now in skills/bot-pr-sweep/apm.yml, and its SKILL.md frontmatter has no version:. Compared with 692c030, the merge brings in only #52's changes to bot-pr-sweep. All 25 skills still have an apm.yml, and CI is green on this commit.

The earlier review stands, and I resolved the last open thread (the AGENTS.md rewrap, applied in 692c030). Merging is for a maintainer to decide.


Generated by Claude Code

@CodyCBakerPhD

Copy link
Copy Markdown
Contributor Author

Leaving this to @leej3 as our APM 'point person'

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants