docs: make the marketplace plugin install the documented default - #1195
Merged
Conversation
…in skill names Add `docs/quick-start.md` as the entry point and make the marketplace install the recommended path, with per-family plugins as the default shape and the all-in-one `magpie` plugin marked not recommended. - Quick start covers Claude Code, Codex, VS Code/Copilot and Gemini, a "what each family solves" chapter, and the secure-isolation step. - Each `docs/<family>/README.md` gains an "Install & first runs" section with the one install command and worked examples. - Terminology: "adopt" names the project's relationship with Magpie and is no longer the name of an install method; the snapshot path is the "pinned snapshot install", and self-adoption is the default inside a Magpie checkout. - Family plugins advertise de-stuttered skill aliases via their symlink names (`/magpie-security:issue-triage`). Source directories keep their prefix: the portable install flattens all skills into one namespace where it is the only thing separating `issue-stale-sweep` from `pr-stale-sweep`, and `setup` would strip to an empty name. - Docs use the plugin form; skills refer to each other by bare skill name, which is correct under either install method; snapshot guides keep the single-token form and say so. - Always-on token figures were wrong (~21.7k claimed, ~8.6k measured). `tools/dev/estimate-skill-tokens.py` measures the advertised surface (frontmatter name + description) and gates the published tables. - `check-doc-sync.py` gains three guards: per-family plugin counts, no family-name stutter, and portable-form invocations must declare which install they mean. - Eval fixtures re-synced with the swept skill text. Screenshots under `assets/quickstart/` ship as placeholders; the capture checklist is in `assets/quickstart/README.md`. Generated-by: Claude Code (Opus 5)
The quick-start now documents the marketplace plugin install as the default, but the setup skill itself still went straight to the snapshot install — docs promising a default the skill did not implement. Adds the M1-M5 marketplace path, the marketplace-install checks in verify, the locks reference, and the matching spec-loop criteria. Generated-by: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01M7zttXzAM1wbTdBAjJCECv
`tools/dev/capture-screenshot.sh <target>` captures one shot straight into the path the docs already reference, resized to the 1700px the other `assets/` captures use and EXIF-stripped. It prints what to frame — and the no-secrets check — before opening the crosshair, because framing is the part that is easy to get wrong and expensive to notice later. Valid family targets come from the live `family:` frontmatter, so a typo fails instead of writing a file nothing references. macOS only: Screen Recording permission is granted per calling application, so it has to run from the user's own terminal. Generated-by: Claude Code (Opus 5)
…e set honest Replaces eleven generated placeholders with real /plugin captures taken in a scratch project, and adds check-quickstart-screenshots.py: it ties each harness shot to the manifest that makes that harness real, refuses orphans and off-geometry captures, and reports the three still-pending placeholders without blocking the commit. Generated-by: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01M7zttXzAM1wbTdBAjJCECv
The sweep stripped /magpie- more bluntly than the naming rule warrants. setup/SKILL.md ended up saying the prefix is added and then not used; the stats dashboards rendered pasteable commands valid on no install path; list-skills' when_to_use named a string nobody types; the README's front-door example was /dependency-audit; and the secure-agent checklist mixed a snapshot action into a marketplace-form block. Also corrects check-doc-sync's own docstring, which said eight checks where main() runs ten. Generated-by: Claude Opus 5
Eleven real captures have landed, so the 'all placeholders' framing was stale in the same commit that made it stale, as was 'the four screenshots' for a set of fourteen. The documented ~1400px also contradicted the 1700px both the capture script and the new checker require — a contributor following the docs produced a file the hook rejects. The capture script now refuses a source window under 1700px rather than letting the sips fallback silently upscale, and no longer leaks a temp file per run. Generated-by: Claude Opus 5
Its docstring claimed each shot was verified 'at the exact path the docs reference' while the checker never opened a doc; the orphan sweep saw only two directories; the family scan read any line beginning family: rather than the frontmatter block; and a comment asserted the capture script only ever shrinks, which the sips fallback does not. Generated-by: Claude Opus 5
It cited the unadopted-repo and mixed-team pages as evidence that the marketplace install alone suffices, but both taught a git clone plus user-scope symlink recipe — the very work the marketplace install removes. Both now open with the marketplace path and demote the clone to the fallback. Also flags VS Code and Gemini as not yet live-installed, matching the verification table, and drops a doubled horizontal rule. Generated-by: Claude Opus 5
It read as an absolute directly above the new marketplace-first criterion, though it is now true only of the pinned-snapshot install. Generated-by: Claude Opus 5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Magpie ships manifests for four agent plugin mechanisms, but the documentation still led with the pinned-snapshot install. This makes the marketplace install the default path everywhere and demotes the snapshot to a named fallback, for the cases a marketplace cannot reach: no plugin mechanism, the signed ASF artefact, or a project that wants every contributor and CI job pinned to one committed version.
What's in it
docs/setup/rewritten marketplace-first, with the three invocation forms (/magpie-<skill>,/magpie-<family>:<skill>,/magpie:<skill>) documented in one table and enforced by two newcheck-doc-syncrules.setupskill gains the marketplace path it was missing (Steps M1–M5) plus marketplace-install checks inverify. Without this the tree documented a default the skill did not implement./plugincaptures replace generated placeholders, andcheck-quickstart-screenshots.pyties each harness shot to the manifest that makes that harness real, rejects orphans and off-geometry captures, and reports the still-pending placeholders without blocking commits.Still placeholders:
codex,vscodeandgemini. The checker names them on every run.Review fixes included: a de-stutter sweep had stripped
/magpie-more bluntly than the naming rule warrants — the stats dashboards were rendering "pasteable" commands valid on no install path,list-skills' routing trigger named a string nobody types, and the README's front-door example was/dependency-audit. Also corrected: docs that claimed ~1400px where the hook requires 1700, two pages the quick-start cited as evidence while they taught the opposite recipe, and several statements the same commits had made stale.🤖 Generated with Claude Code
https://claude.ai/code/session_01M7zttXzAM1wbTdBAjJCECv