From db55553c7ba373662caddfa08cdd18425ff3db10 Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Tue, 28 Jul 2026 16:47:31 +1000 Subject: [PATCH 1/2] Docs: the CLI install route, and check the branch not just the status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two gaps the first real run of /audit:issues (#16) found within minutes of someone following the tutorial. **`/plugin` does not exist outside the terminal CLI.** The VS Code extension and the web app answer "/plugin isn't available in this environment", and every install instruction in this repo offered only the slash form. `claude plugin marketplace add` / `claude plugin install` do the same job from any shell. Documented in docs/using-skills.md, which owns setup; the tutorial now leads with the CLI form because it is the one that works everywhere, and README gets a pointer rather than a third copy. All three now also say to restart the session — plugins register at startup, which is its own silent stumbling block. **A clean tree on the wrong branch passed the preflight.** The tutorial told the reader to check `git status` before starting but never to be on the default branch. Phase 2 asks whether an issue still reproduces on `main`; run from a feature branch and every answer is measured against unmerged work instead, which invalidates the phase the run exists to test — while passing the check the tutorial did specify. Caught on a real checkout sitting two commits ahead on a feature branch. Docs only; no plugin version change. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 2 ++ docs/tutorial-run-an-audit.md | 19 +++++++++++++------ docs/using-skills.md | 9 +++++++++ 3 files changed, 24 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cc79a2b..7daaa53 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,8 @@ Lecture repositories opt in by checking the following into their `.claude/settin /plugin install audit@quantecon ``` +Those are slash commands in a Claude Code session. `/plugin` is a terminal-CLI built-in, so in the VS Code extension or the web app use the equivalent `claude plugin …` CLI commands instead — see [using-skills § Setup](docs/using-skills.md#setup). + ### CI (GitHub Actions) The official action accepts the marketplace and plugin directly: diff --git a/docs/tutorial-run-an-audit.md b/docs/tutorial-run-an-audit.md index 5c90372..cc6a060 100644 --- a/docs/tutorial-run-an-audit.md +++ b/docs/tutorial-run-an-audit.md @@ -15,21 +15,28 @@ Canonical references (this tutorial points, never restates): the procedure in [S ## Step 0 — install the plugin +```bash +claude plugin marketplace add QuantEcon/skills +claude plugin install audit@quantecon ``` -/plugin marketplace add QuantEcon/skills -/plugin install audit@quantecon -``` -Confirm with `/plugin list`; the version should read **0.1.2**. If `/audit:issues` does not appear in the slash menu, see [using-skills § troubleshooting](using-skills.md#updating-and-troubleshooting) — natural-language invocation ("audit every issue in this repo") works on any version. +**Then restart your session** — plugins register at startup, so the skill does not appear until you reopen. + +The `/plugin marketplace add …` slash form does the same job, but it is a *terminal-CLI built-in*: the VS Code extension and the web app answer `/plugin isn't available in this environment`, while the `claude plugin` CLI above works from any shell. Confirm with `claude plugin list` — the version should read **0.1.2**. + +If `/audit:issues` is still unrecognised after restarting, the plugin-prefixed slash form needs Claude Code 2.1.216+; the bare `/issues` works on older builds, and natural-language invocation ("audit every issue in this repo, output to …") works on any version ([using-skills § troubleshooting](using-skills.md#updating-and-troubleshooting)). ## Step 1 — put the working directory where the repo already ignores it ```bash cd ~/work/quantecon/action-translation -git status --short # must be clean before you start — it is the read-only baseline -git check-ignore -v .dev/scratch/x # → .gitignore:… .dev/scratch/* +git checkout main && git pull --ff-only # phase 2 verifies against the DEFAULT branch +git status --short # must be empty — the read-only baseline +git check-ignore -v .dev/scratch/x # → .gitignore:… .dev/scratch/* ``` +**Be on the default branch, not merely clean.** Phase 2's core question is whether an issue still reproduces on `main`; run from a feature branch and every answer is measured against your unmerged work instead. A clean tree on the wrong branch passes the `git status` check and silently invalidates the phase the whole run exists to test — so check the branch, not just the status. + `action-translation` has a `.dev/` notes system whose `.dev/scratch/*` is already gitignored, which makes it the first-choice working directory: the run leaves `git status` completely clean, and no `.gitignore` edit is needed — that would itself be a change to a tracked file. Repos without one fall back to an untracked `.audit/` at the root ([SKILL.md § Working directory](../audit/skills/issues/SKILL.md)). ## Step 2 — invoke diff --git a/docs/using-skills.md b/docs/using-skills.md index 879ee60..dac2473 100644 --- a/docs/using-skills.md +++ b/docs/using-skills.md @@ -15,6 +15,15 @@ For lecture authors, reviewers, and maintainers who want to *use* the skills. (B /plugin install audit@quantecon # maintainer-facing bulk audits ``` +**`/plugin` is a terminal-CLI built-in**, so the VS Code extension and the web app answer `/plugin isn't available in this environment`. The `claude plugin` CLI does the same job from any shell and works everywhere: + +```bash +claude plugin marketplace add QuantEcon/skills +claude plugin install audit@quantecon # and/or qe@quantecon, benchmark@quantecon +``` + +Either route, **restart the session afterwards** — plugins register at startup, so a newly installed skill is absent until you reopen. `claude plugin list` shows what is installed and at which version. + **In CI** — `anthropics/claude-code-action@v1` accepts `plugin_marketplaces` and `plugins` inputs directly; see the repo README for the workflow snippet. ## Invoking a skill From 611f55245559f82c499855c877f9d104ac14f29f Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Tue, 28 Jul 2026 16:53:45 +1000 Subject: [PATCH 2/2] README: state the restart step where the install commands are The manual install block delegated the restart note to using-skills.md, which made the PR description's "all three now say to restart" untrue and, worse, left the gotcha one click away from the four commands that trigger it. A skill that has not registered yet looks exactly like a failed install, so this belongs at the point of use; the reasoning stays in using-skills.md. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7daaa53..69638e6 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ Lecture repositories opt in by checking the following into their `.claude/settin /plugin install audit@quantecon ``` -Those are slash commands in a Claude Code session. `/plugin` is a terminal-CLI built-in, so in the VS Code extension or the web app use the equivalent `claude plugin …` CLI commands instead — see [using-skills § Setup](docs/using-skills.md#setup). +Those are slash commands in a Claude Code session; **restart the session afterwards**, since plugins register at startup. `/plugin` is a terminal-CLI built-in, so in the VS Code extension or the web app use the equivalent `claude plugin …` CLI commands instead — see [using-skills § Setup](docs/using-skills.md#setup). ### CI (GitHub Actions)