diff --git a/.github/maintainer/decisions.md b/.github/maintainer/decisions.md index 26503b0..196dbd0 100644 --- a/.github/maintainer/decisions.md +++ b/.github/maintainer/decisions.md @@ -24,3 +24,14 @@ Decisions recorded here are the project-level calls: scope, policy, architecture **Decision:** Published annotated tag `v1.4.1` on commit `0dd3e2b` (tip of main after #1 + #2 + #3) and a public GitHub Release with notes derived from the CHANGELOG 1.4.1 section. URL: . **Reasoning:** The fix in #1 materially changes install behavior for skills with non-trivial bundles. Cutting a patch release (not a minor) because the change aligns user-facing behavior with what was already promised — skills were supposed to install as directories; previously they installed as a single file. Plugin marketplace consumers tracking `skill-fetch@latest` will pick this up automatically on next plugin update. **Follow-up:** Monitor issues for 24–48h for any edge cases in unusual skill repo layouts (e.g., SKILL.md at repo root, branch names with `/`, private repos requiring auth). + +### [PR:5] Merged — Remove `.mcp.json` to stop shadowing user-scope skillsmp +**Date:** 2026-04-23 +**Decision:** Deleted repo-root `.mcp.json` (introduced by commit `db8deba`). Plugin payload is the entire repo (`marketplace.json` → `source: "./"`), so shipping a project-scope `.mcp.json` with no `SKILLSMP_API_KEY` caused every v1.4.1 plugin user's user-scope `skillsmp` registration (the one with the key) to be silently overridden; SkillsMP Sources 1–2 failed with no visible error. +**Reasoning:** Public repos cannot carry the required secret, so a committed `.mcp.json` will always be keyless and harmful. README §SkillsMP and `/fetch-skill-config` already guide users to register the server at user scope — that's the only path that works. Fix is strictly subtractive; non-plugin install paths (`npx skills add`, `install.sh`, `install.py`) were unaffected because they whitelist `skills/skill-fetch/*` only. CI green on all three checks before merge. + +### Cut release `v1.4.2 — Fix SkillsMP MCP shadow bug` +**Date:** 2026-04-23 +**Decision:** Published annotated tag `v1.4.2` on merge commit `094c6f8` and GitHub Release with migration note (run `claude plugin update`, then register MCP at user scope). URL: . +**Reasoning:** Correctness bug — SkillsMP search silently broken for all v1.4.1 plugin users. Patch release (not minor) because fix restores intended behavior without API changes. `git pull`-based plugin updates auto-propagate the file deletion, so existing plugin users heal on next `claude plugin update`. +**Follow-up:** Download + update local plugin to verify the deletion propagates cleanly on a real install; watch for issues reporting "skillsmp not found" (expected — user must register at user scope post-fix) vs actual regressions. diff --git a/.github/maintainer/patterns.md b/.github/maintainer/patterns.md index 6cff1cc..0eac1b5 100644 --- a/.github/maintainer/patterns.md +++ b/.github/maintainer/patterns.md @@ -10,6 +10,15 @@ Patterns the maintainer agent has learned while operating the repo. Use these to - **Resolution:** Full git-tree enumeration via `scripts/fetch-skill-bundle.sh` (PR:1). - **Prevention:** Never hardcode subdir names or extensions in install/scan logic. Walk the tree. +### Project-scope `.mcp.json` in a public repo shadowing user-scope MCP registrations +- **First observed:** 2026-04-23 (internal review → [PR:5], affected v1.4.1) +- **Cause:** `db8deba` committed a repo-root `.mcp.json` that registered `skillsmp` without an API key, intending "auto-provision". Claude Code's MCP resolution gives project-scope precedence over user-scope, so the keyless server overrode the user-scope version where the key lives. Compounded by `marketplace.json` having `source: "./"` — the whole repo is the plugin payload, so the file shipped to every plugin user. +- **Resolution:** Delete `.mcp.json`; point users at `claude mcp add --scope user ...` / `/fetch-skill-config` (PR:5). +- **Prevention:** + - Any MCP server requiring an API key or other secret MUST be registered at **user scope** via `claude mcp add --scope user` or via an interactive setup helper. Never commit `.mcp.json` to a public repo for such a server. + - Project-scope `.mcp.json` is only appropriate for MCP servers that (a) need no secrets, or (b) read secrets from the user's environment / `~/.claude/skills/.fetch-config.json` at runtime — and even then, the plugin payload implications (`source: "./"`) must be considered. + - Check `marketplace.json`'s `source` when reasoning about what ships to users. If `./`, treat every repo-root config file as user-visible. + ## Codebase Patterns - SKILL.md is the public contract; references/ files are progressive disclosure. Keep SKILL.md lean; push detail down into reference files. diff --git a/.github/maintainer/runs.md b/.github/maintainer/runs.md index 4c4dae1..3a0af0c 100644 --- a/.github/maintainer/runs.md +++ b/.github/maintainer/runs.md @@ -5,3 +5,4 @@ Append one entry per triage run. Keep entries terse; link to the full report dir | Date | Report | Issues/PRs scanned | Notes | |------|--------|---------------------|-------| | 2026-04-23 | _(no formal report)_ | 0 open issues / 0 open PRs at start | State bootstrap + shipped three maintainer-authored PRs (#1 #2 #3) and cut release `v1.4.1`. No external triage surface yet. | +| 2026-04-23 | _(no formal report)_ | 0 open issues / 0 open PRs | Discovered the `.mcp.json` shadow bug during user-reported "two skillsmp" confusion. Shipped [PR:5] and cut `v1.4.2`. `triage.ts` skipped — zero external surface. Next run should actually execute the script once there are community-reported items. |