skill-adopt

# Skill Adopt Safely search, review, and install Claude Code skills through a 3-stage pipeline: 1. **Security Audit** (`/skill-security-audit`) — behavioral safety check 2. **Quality Validation** (`/skill-validator`) — Claude Code standards check 3. **User Decision** — you choose whether to install and whether to apply suggested improvements No skill is installed without passing Stage 1. No skill is installed without your explicit confirmation. --- ## Usage **Mode A: Find and install an external skill** ``` /skill-adopt [task description] /skill-adopt --ask-me [task description] # confirm each fix before applying ``` **Mode B: Validate a skill you already have (local path)** ``` /skill-adopt --validate-only [path to SKILL.md or folder] /skill-adopt --validate-only --ask-me [path] ``` --- ## Stage 0: Check Staging Area Before starting, check if there are leftover files from a previous interrupted run: ```bash ls ~/.claude/skills/.staging 2>/dev/null ``` If files exist, ask the user whether to clean up or continue from where it left off. --- ## Stage A: Find Candidates (Mode A only) Search for matching skills: ```bash npx skills find "[task description]" ``` Filter criteria: - 1,000+ installs preferred; under 100 excluded unless official source - Official sources (anthropics, vercel-labs) have no install threshold - Present top 3 matches and ask user to confirm before proceeding If `npx` is not available: `brew install node` --- ## Stage B: Stage the Download (Mode A only) Download the confirmed skill to a staging area — do NOT install directly: ```bash STAGING=~/.claude/skills/.staging mkdir -p "$STAGING" npx skills add <owner/repo@skill> --dir "$STAGING" --no-activate ``` If `--no-activate` is not supported, manually download to the staging directory. --- ## Stage 1: Security Audit ⚠️ Required Gate Run `/skill-security-audit` on the staged (or provided) skill path. This checks for: - CLAUDE.md auto-injection of routing rules - Tool blocking / hijacking Claude's tool selection - Proactive workflow takeover - Auto-commits to user config files - Embedded promotional content - Telemetry and remote data transmission **If any 🔴 issue is found:** - Pause the entire flow - Present the audit report to the user - Use AskUserQuestion: > Security audit found [N] issue(s). How would you like to proceed? > > A) Fix all issues automatically, then continue > B) I'll fix them myself — re-run /skill-adopt when ready > C) Cancel installation Do not proceed past Stage 1 until the user explicitly chooses A or the audit returns no 🔴 items. --- ## Stage 2: Quality Validation Run `/skill-validator` on the skill to check against Claude Code's 9 quality principles: 1. Skip the obvious 2. Build a Gotchas section 3. Progressive disclosure 4. Don't railroad 5. Description = trigger 6. Think through setup 7. Store data 8. Give it code 9. On-demand hooks Output the quality report. Then ask: > Quality check complete ([X]/9 passed). Would you like to: > > A) Apply all suggested improvements automatically > B) Review and approve each improvement one by one (`--ask-me`) > C) Skip quality improvements and install as-is Quality issues do NOT block installation — the user decides whether to apply fixes. --- ## Stage 3: Install After Stages 1 and 2 are resolved (per user choices): ```bash cp -r ~/.claude/skills/.staging/<skill-name> ~/.claude/skills/<skill-name> rm -rf ~/.claude/skills/.staging/<skill-name> ``` Confirm installation by listing the new skill: ```bash ls ~/.claude/skills/<skill-name> ``` --- ## Stage 4: Log the Result Append a record to the install log: ```bash echo '{"date":"<ISO8601>","skill":"<name>","action":"installed|rejected","stage":"security|quality|user","notes":"<reason>"}' \ >> "${CLAUDE_PLUGIN_DATA}/skill-install-log.jsonl" ``` The user can say "show my skill install history" to review past decisions. --- ## Mode B: --validate-only Run Stage 1 (security audit) and Stage 2 (quality validation) on the provided path. At the end, ask whether to install. Skip staging — if user confirms install, copy directly from the provided path. --- ## Gotchas - `npx skills add --no-activate` may not be supported on all versions. If missing, manually download to a temp directory and copy to staging. - After `skill-validator` modifies a SKILL.md, re-read it to confirm the frontmatter YAML is intact (description fields containing colons break YAML parsing). - Some skills are folder-structured with multiple `.md` files. Pass the folder path (not just SKILL.md) to both `/skill-security-audit` and `/skill-validator`. - The staging directory is not auto-cleaned on interruption. Always check for leftovers at the start of each run. - A skill that passes both audits is still your responsibility. Read the skill description to make sure it triggers only when you intend it to. ## Category Business Automation — Consolidates a multi-step skill review and installation workflow into a single safe command.