---
name: skill-adopt
description: Safely find, vet, and install any Claude Code skill through a 3-stage review pipeline. Trigger on "install skill", "find skill", "add skill", "安裝 skill", "找 skill", "幫我裝 skill", "新增 skill", "validate skill I made", "幫我驗證這個 skill", "審查我寫的 skill".
---

# 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.