Implementation Skill

Internal Claude plugins for Athos Commerce implementation work. Distributed as a plugin marketplace so the team gets updates by pulling, not by re-uploading zips.

Private repo. Installing from a marketplace in a private repo requires each user to have GitHub access and working git credentials. Confirm a teammate can install before rolling out widely — this is the most common first-run failure.

Org migration. This repo currently lives under searchspring and will move to athoscommerce. The marketplace identifier is athos-commerce and deliberately does not change with it — users reference plugins as athos-implementation@athos-commerce, and renaming the marketplace later would break every enabledPlugins entry and force everyone to re-add it. Only the source repo path changes on migration.

What's in here

Plugin	Contents
athos-implementation	snap-templates skill — intake workflow, reference-markup approach for Result.tsx, captured-spec procedure for toolbar/facet/pagination fidelity, and four inspection scripts

Install (one time)

In Cowork or Claude Code:

/plugin marketplace add searchspring/implementation-skill
/plugin install athos-implementation@athos-commerce

Update

/plugin marketplace update athos-commerce

Admins can push this to everyone automatically instead — see Org rollout.

Manual fallback

If the marketplace isn't reachable, grab the .skill file from the latest release and upload it via Settings. This is a fallback, not the normal path: manually uploaded copies don't receive updates and drift apart.

Org rollout

On Team or Enterprise, an admin can deploy this without anyone running a command, via managed settings:

{
  "extraKnownMarketplaces": {
    "athos-commerce": {
      "source": { "source": "github", "repo": "searchspring/implementation-skill" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "athos-implementation@athos-commerce": true
  }
}

autoUpdate keeps the team current without per-user action. Force-enabling in managed settings also prevents individuals disabling it locally.

Repo layout

.claude-plugin/marketplace.json     catalog — lists plugins and their versions
plugins/<plugin>/
  .claude-plugin/plugin.json        plugin manifest (only this file goes in .claude-plugin/)
  skills/<skill>/SKILL.md           the skill itself
  skills/<skill>/references/        progressive-disclosure docs
  skills/<skill>/scripts/           bundled executables
ci/                                 validation, version gate, packaging
tests/                              script tests + fixtures

Note: skill folders must not contain a README.md — that's a hard rule, and CI enforces it. This repo-level README is for humans and is fine.

Contributing

1. Branch, make the change.
2. Bump metadata.version in SKILL.md, and the matching version in plugin.json and marketplace.json. All three must agree — CI checks this.
3. Add a CHANGELOG.md entry: a ## <version> heading, a few consumer-facing bullets, and an Action: line saying what installers must do (or Action: none). CI blocks a version bump without one. Keep root-cause detail out of it — that goes in the skill's references/test-cases.md.
4. If you changed a skill's description, re-run the triggering probe and append the result to that skill's references/test-cases.md. CI blocks a description change without it.
5. Open a PR. CI runs structure validation, script tests, and the version gate.
6. Merge, then tag vX.Y.Z to publish a release. The tag must match the manifest versions.

Where things get written

File	Holds	Audience
CHANGELOG.md	What changed per version, plus an Action: line	Whoever installs it
references/test-cases.md	Test cases and a dated results log with root-cause detail	Maintainers
references/team-notes.md	Durable technical knowledge, not tied to a version	Implementers at work
GitHub release notes	Raw merged-PR list, generated automatically	Anyone auditing

Don't restate one in another. The CHANGELOG drifting into root-cause essays is the failure mode this table exists to prevent.

Run the checks locally

python3 ci/validate_skills.py
python3 -m unittest discover -s tests -v
python3 ci/check_version_bump.py --base origin/production
python3 ci/build_artifacts.py

No dependencies beyond Python 3.12 and Node (Node only for a syntax check on capture_styles.js).