denniswei9898/claude-skill-safety-kit/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:

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:

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:

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):

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:

ls ~/.claude/skills/<skill-name>

Stage 4: Log the Result

Append a record to the install log:

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.