Table of Contents generated with DocToc
Scope. Works on any project, ASF or not — no Apache-Software-Foundation-specific assumptions baked in.
The setup skill family is the prerequisite for running any framework skill. It walks a new adopter (or a fresh dev machine on an existing adopter) through the secure-agent install — pinned system tools, the project-scope .claude/settings.json sandbox block, the claude-iso clean-env wrapper, the user-scope hooks — and through the ongoing housekeeping (verify install drift, pull framework updates, sync shared user-scope config across machines).
Why a dedicated install skill family? The framework‘s other skills run against pre-disclosure CVE content, private mailing lists, and in-flight tracker discussions. Without the layered defence the setup skills install (sandbox + permission rules + clean-env wrapper), a misconfigured agent can leak credentials or pre-disclosure content into the model provider’s training data or into a public PR. The setup family is what makes the rest of the framework safe to use.
| Skill | Purpose |
|---|---|
setup-isolated-setup-install | First-time install of the secure agent setup. |
setup-isolated-setup-verify | Verify the secure setup landed correctly (static checks on settings.json, hooks, pinned versions). |
setup-isolated-setup-doctor | Diagnose in-session sandbox friction (SSH agent, port bind, docker/podman socket) and map each fail to a catalog entry. |
setup-isolated-setup-update | Surface drift between the installed setup and the framework's latest. |
setup upgrade | Pull the framework checkout to latest origin/main. |
setup verify | Verify the framework is integrated correctly into an adopter tracker. |
setup-status | Render a Markdown adoption dashboard (install pin, drift, wired agent targets, installed skill families, symlink health) and adjust the wiring in place. |
setup-shared-config-sync | Commit + push the user's shared Claude config to its sync repo. |
setup-override-upstream | Promote a local .apache-magpie-overrides/<skill>.md file into a PR against apache/magpie; prompts to remove the override once merged and upgraded. |
setup-upstream-fix | Turn a framework bug or quirk hit mid-session into a fix PR against apache/magpie, after checking for an existing issue or PR that already covers it. |
secure-agent-setup.md — full install walkthrough. The authoritative reference the setup-isolated-setup-install skill steps through.secure-agent-internals.md — how the layered defence works (sandbox + permission rules + clean-env wrapper) and why each layer exists.install-recipes.md — copy-pasteable shell recipes (svn-zip / git-tag / git-branch) for bootstrapping setup into a new adopter repo.unadopt.md — counterpart to install-recipes.md: remove the framework artefacts the adopt flow installed. One path, full plan surfaced before any write.sandbox-troubleshooting.md — catalog of known sandbox-shaped failure modes (SSH agent / Yubikey unreachable, test port-bind blocked, docker/podman socket denied) with symptom → root cause → settings.json fix for each. The page to grep when a normal-looking operation fails in the sandbox in an unexpected way.new dev machine ↓ setup-isolated-setup-install isolated setup installed ↓ setup-isolated-setup-verify (any time, especially after Claude Code upgrade) verified ↓ setup-isolated-setup-update (monthly / after Claude Code upgrade) drift surfaced ↓ setup-upgrade (when framework releases something new) framework checkout up to date
setup-shared-config-sync is orthogonal — it commits the user's ~/.claude/CLAUDE.md and other shared config to a private sync repo so a fresh dev machine can pick it up (run after editing any file under ~/.claude-config/).
docs/prerequisites.md — what each framework skill needs (Claude Code, Gmail MCP, GitHub auth, browser, etc.).