clone-skill

Clone Skill

Copy an existing Claude Code skill from an external source into one of this workspace's plugins, recording provenance in attributions.md.

Intended as a precursor to tweaking the cloned skill — typically to lock in a snapshot or fork-and-modify. This skill never tracks upstream changes; once a skill is cloned, it lives standalone in its target plugin.

When to Activate

• "Clone the <skill-name> skill"
• "Copy the <skill-name> skill into <plugin>"
• "I want to copy a skill from <owner/repo>"
• "Fork <skill-name> from <source> into <plugin>"

Inputs

Collect these four values, asking only for what the user has not already supplied. Confirm each value back to the user as it is collected — Reason is collected and confirmed at Workflow Step 7, not upfront.

1. Skill name — the directory/skill identifier as it appears in the source (e.g. devcontainer-setup).

2. Source — accepted in either form:

   • GitHub shorthand owner/repo — expand to https://github.com/<owner>/<repo>.
   • A full URL beginning with https:// or http:// — use as-is.
   • If the input matches neither shape, re-prompt with the format hint: "Use owner/repo or a full https:// URL."

3. Target plugin — the directory name under plugins/ (e.g. devcontainer-skills). If the user supplies mixed case, propose the kebab-case form and confirm before proceeding. Never silently apply the normalization.

4. Reason — free-text, asked just before the copy step (Step 7 of the workflow). The reason is used twice:

   • It populates the comment column in attributions.md verbatim (with newlines collapsed to spaces and literal | escaped as \|).
   • It drives inference of the attribution column. Pick forked if the reason mentions intent to modify (any of: modify, change, fix, remove, tweak, address, adapt, customize, replace); otherwise pick cloned. Tell the user the inferred value and offer an override. The override may be any of cloned, forked, or based on.

Workflow

Execute these steps in order. If any step fails or the user aborts, run the cleanup defined in Step 12 and exit without further repo changes.

Step 1 — Collect inputs

Ask the user for whichever of the four inputs (Skill name, Source, Target plugin, Reason) are not already supplied. Reason is deferred until just before Step 7. Validate Source per the format rules above before proceeding.

Step 2 — Resolve target plugin

Check whether the target plugin directory exists:

ls -d plugins/<target>/ 2>/dev/null

• If it exists: continue to Step 3.
• If it does NOT exist: tell the user "<target> doesn't exist yet — I'll scaffold it via work-on-plugin and come back." Then invoke the work-on-plugin skill (using the Skill tool, not a bash command) with the target name. After it returns, re-check that plugins/<target>/ now exists. If not, abort.

Step 3 — Check for collision

ls -d plugins/<target>/skills/<skill-name>/ 2>/dev/null

If the directory exists, prompt the user with three options:

• overwrite — proceed; the existing skill directory will be replaced after Step 7 confirmation.
• skip — abort cleanly. Skip cleanup (no temp dir yet) and exit with a one-line message: "Skipped: <skill-name> already exists in <target>."
• rename — ask for a new directory name. Re-check for collision under the new name; allow up to 3 rename attempts before aborting with: "Too many name collisions — aborting."

Record the chosen <final-name> (original or renamed) for use in Steps 8 and 10.

Step 4 — Create the temp install dir

TEMP_DIR=$(mktemp -d -t clone-skill-XXXXXX)
echo '{}' > "$TEMP_DIR/package.json"

The empty package.json ensures npx does not refuse to run for lack of a project manifest. Remember $TEMP_DIR for Steps 5, 6, 7, and 12.

Step 5 — Snapshot the temp dir before install

( cd "$TEMP_DIR" && find . -type f | sort ) > "$TEMP_DIR/.before.txt"

Step 6 — Run the install

( cd "$TEMP_DIR" && npx skills add <expanded-source-url> --skill <skill-name> --yes 2>&1 )

If the command exits non-zero:

• Capture and show the full stderr to the user.
• Run cleanup (Step 12).
• Abort. Do not proceed to Step 7.

Step 7 — Snapshot after, diff, and confirm

( cd "$TEMP_DIR" && find . -type f | sort ) > "$TEMP_DIR/.after.txt"
NEW_FILES=$(comm -13 "$TEMP_DIR/.before.txt" "$TEMP_DIR/.after.txt")
echo "$NEW_FILES"

Filter NEW_FILES to remove noise that npx skills add produces beyond the skill's real files. Discard any paths that:

• equal ./skills-lock.json
• start with ./.claude/skills/ (symlink — just a pointer)
• start with ./.factory/skills/ (symlink — just a pointer)
• start with ./.kiro/skills/ (symlink — just a pointer)
• equal ./package.json (our own empty manifest from Step 4)

The canonical skill files live under ./.agents/skills/<skill-name>/. After filtering, NEW_FILES should contain only those canonical paths unless the skill brought extra dependencies.

Then:

• If filtered NEW_FILES is empty: tell the user "npx skills add reported success but produced no new canonical files — aborting." Run cleanup (Step 12). Do NOT update attributions.
• If filtered NEW_FILES contains paths only under ./.agents/skills/<skill-name>/: ask "About to copy these N files into plugins/<target>/skills/<final-name>/. Proceed?"
• If filtered NEW_FILES contains paths outside ./.agents/skills/<skill-name>/ (e.g. sibling skill directories that were pulled in as dependencies): show the full list and ask "These files live outside the expected skill directory. Copy (a) only ./.agents/skills/<skill-name>/, or (b) everything shown?"

Before issuing the confirm prompt, collect the Reason input (the one input held back from Step 1) and infer the attribution category as described in the Inputs section. Include the inferred attribution in the confirm prompt so the user sees the full picture in one message, e.g.: "About to copy N files into plugins/<target>/skills/<final-name>/ and record attribution as <inferred>. Proceed?"

If the user declines at the confirm prompt: run cleanup (Step 12) and exit with "Cancelled by user — no changes made."

Step 8 — Copy

Create the destination directory and copy the chosen subset, preserving permissions.

SOURCE_PATH is the path determined from the Step 7 diff:

• If the filtered diff showed files only under ./.agents/skills/<skill-name>/, SOURCE_PATH is $TEMP_DIR/.agents/skills/<skill-name>.
• If the user chose "copy everything shown" in Step 7, SOURCE_PATH is the common parent directory of the shown paths (typically $TEMP_DIR/.agents/skills/).

mkdir -p plugins/<target>/skills/
# If overwrite was chosen in Step 3:
rm -rf plugins/<target>/skills/<final-name>/
cp -R "$SOURCE_PATH/" plugins/<target>/skills/<final-name>/

Use cp -R (preserves permissions on macOS/BSD; on GNU systems use cp -a if available — check cp --version first).

Step 9 — Capture commit SHA

SHA=$(git ls-remote <expanded-source-url> HEAD 2>/dev/null | awk '{print substr($1, 1, 7)}')

If SHA is empty, leave it empty — do not abort. The attributions row will record only the URL.

Step 10 — Update attributions.md

See the Attributions file section below for the full rules. Append one row to the table at ./attributions.md. Show the user the row content (with the inferred attribution value) and accept an override before writing.

Step 11 — Update README.md

See the README handling section below.

Step 12 — Cleanup

rm -rf "$TEMP_DIR" || echo "WARNING: failed to clean up $TEMP_DIR — please remove manually"

The cleanup is unconditional — run it on success, failure, or abort. A cleanup failure is a warning only; do not fail the overall operation if the copy already succeeded.

Step 13 — Report

Print a summary:

Cloned <skill-name> from <expanded-source-url>
  → plugins/<target>/skills/<final-name>/ (<N> files)
  → attributions.md row added: <plugin> | <skill> | <source> | <attribution> | <comment>

Attributions file

Location: ./attributions.md at the repo root.

Initial creation

If attributions.md does not exist when Step 10 runs, create it with this exact content (the example row is illustrative and is NOT part of the new file — write only the header):

# Attributions

Skills in this workspace that originated outside this repo. See [README](./README.md) for repo overview.

| plugin | skill | original source | attribution | comment |
|--------|-------|-----------------|-------------|---------|

Then append the new row immediately after the header.

Existing file — has the expected table header

Detect with: grep -Fq '| plugin | skill | original source | attribution | comment |' attributions.md

Append the new row as the last line of the table. Do not rewrite, sort, or deduplicate existing rows.

Existing file — does NOT have the expected table header

Append a fresh table (header + new row) below the existing content, separated by a single blank line. Do not attempt to merge into an unknown structure. Omit the intro paragraph — it is written only during fresh file creation (see above).

Column rules

Column	Rule
plugin	Target plugin directory name.
skill	Final skill directory name (post-rename, if applicable).
original source	<expanded-url> @ <sha> if SHA was resolved in Step 9; just <expanded-url> otherwise.
attribution	One of cloned, forked, based on. The skill emits only cloned or forked from inference. The user override may add based on.
comment	The user's reason on a single line. Collapse newlines to spaces. Escape literal `

README handling

On every clone, ensure the repo-root README.md links to attributions.md.

No README.md exists

Create a minimal one with the template below, substituting the <description ...> placeholder with the output of the jq command that follows.

Template:

# skill-plugins-factory

<description from .claude-plugin/plugin.json>

## Attributions

See [attributions.md](./attributions.md) for the provenance of cloned/forked skills in this workspace.

Get the substitution value via:

jq -r '.description' .claude-plugin/plugin.json

README.md exists, has no link to attributions.md

Append this section at the end of the file:

## Attributions

See [attributions.md](./attributions.md) for the provenance of cloned/forked skills in this workspace.

README.md already links to attributions.md

No-op. Detect with:

grep -q '\battributions\.md\b' README.md

Edge cases & error handling

Situation	Behavior
npx skills add fails	Surface stderr to the user, run Step 12 cleanup, abort with no repo changes.
git ls-remote fails for SHA resolution	Continue without SHA — attribution row records URL only.
Source URL is malformed (neither shorthand nor parseable URL)	Re-prompt the user with the format hint.
User picks skip on collision	Exit cleanly with a one-line message. No temp dir created yet, so no cleanup needed.
User picks rename and the new name also collides	Re-prompt up to 3 times; then abort.
Snapshot diff shows zero new files	Tell the user npx skills reported success but produced nothing; abort without touching attributions.
Snapshot diff shows files outside ./.agents/skills/<skill-name>/	Show the full list and ask whether to copy (a) only ./.agents/skills/<skill-name>/ or (b) everything shown.
attributions.md exists but lacks the expected header	Append a fresh table (header + new row) below the existing content with a blank-line separator.
rm -rf of temp dir fails	Warn the user with the temp path; do not fail the overall operation if the copy already succeeded.
User declines the Step 7 copy confirmation	Run cleanup (Step 12) and exit with "Cancelled by user — no changes made."

Non-goals

• No marketplace updates. .claude-plugin/marketplace.json is work-on-plugin's responsibility (it fires only on plugin creation). Cloning a skill into an existing plugin does not touch the marketplace.
• No update mode. This skill only adds. To replace an already-cloned skill with a fresh upstream snapshot, re-invoke with the overwrite collision option. The new copy will reflect the current upstream HEAD, not the original SHA.
• One skill per invocation. Multi-skill clones are not supported.
• No source-content modification. Files copied from the temp install land verbatim. Provenance lives only in attributions.md, not inside the cloned skill files.
• No persistent install cache. Each invocation creates and destroys its own temp dir.