--- name: meta-adopting-external-skills description: Use when importing, adopting, forking, or integrating a useful third-party Claude Code skill into the bitranox marketplace - given a repo URL, an installed plugin path, or a pasted SKILL.md - or when asked to bring an external skill up to bitranox standards. The adopted skill is added alongside the user's other installed plugins, never replacing them. --- # Adopting External Skills Take a useful-but-imperfect third-party skill, raise it to bitranox standards, and ship it from this marketplace so every install benefits. The skill stays correct legally and never disturbs the user's other plugins. **Core principle: upstream-first and coexist.** Improve the skill, push the improvement back to its original author first, and keep a bitranox copy only if upstream stalls or rejects it. The bitranox copy lives beside the user's other plugins; you never uninstall or disable anything. ## Where you must be standing Every path in this skill is relative to a CHECKOUT OF THE MARKETPLACE REPO, not to an installed plugin - `plugins/bitranox/.claude-plugin/plugin.json`, `plugins/bitranox/hooks/repo-gate.py`, `CONTRIBUTING.md` at the repo root. Adoption commits to that repo, so there is nowhere else the work can happen; `adopt_skill.py` agrees, resolving the repo root by searching upward for `plugins/bitranox/.claude-plugin/plugin.json` and failing if it never finds one. From an INSTALLED plugin those paths resolve to nothing, because an install is the plugin directory alone - it has `hooks/` and `skills/` at its top level and no `plugins/bitranox/` anywhere. If that is where you are, clone the marketplace repo and work there. ## When to use User-directed only. The user points you at a specific external skill: a repo URL, a path to an installed plugin/skill directory, or a pasted `SKILL.md`. Do not go hunting for candidates and do not scan installed marketplaces. Not for skills you write from scratch (use `bitranox:meta-skill-writer`) and not for a skill that lives only in a project's own `.claude/skills/` (that stays in that project). ## Iron rules - **License gate is blocking.** No adoption work begins until the upstream license is verified as redistributable and MIT-compatible. No exceptions. - **Never touch the user's other plugins.** Do not run `/plugin uninstall`, edit `~/.claude/settings.json`, or modify any installed-plugin directory. Adoption only ever adds a skill to this repo. - **Upstream-first.** The bitranox copy is the fallback, not the default. Try to fix it at the source before you keep a fork. ## Step 1 - License gate (blocking) > Tiering: offload the bounded analysis of a large external repo to a **`sonnet`** subagent (summarize > behavior, surface license evidence, list naming/cross-reference normalization deltas) so the whole > third-party tree stays out of your context; the license accept/reject mapping is mechanical > (**`haiku`**). The no-license-found path stays a user decision. Tiers: "Concrete tiers" in > `bitranox:process-agents-subagent-driven-development`. Find the license. Look beyond the skill's own folder: the source repo root (`LICENSE`/`COPYING`), SPDX headers, the `license` field of any `plugin.json` / `package.json` / `pyproject.toml` / marketplace manifest, and a README license section. - **Accept** the permissive family: MIT, BSD-2-Clause, BSD-3-Clause, ISC, Apache-2.0. Capture the upstream copyright line verbatim and the full license text. For **Apache-2.0** also capture any upstream `NOTICE` file and record that you modified the files (Apache-2.0 requires stating changes; adoption always modifies). - **Reject** copyleft (GPL, LGPL, AGPL) and proprietary/all-rights-reserved licenses: they cannot be redistributed inside this MIT collection. Stop. - **No license found anywhere** means all rights reserved, not permissive - **never assume MIT**. Stop the mechanical work, research online (the source repo's detected license, the author's other repos or registry entries, any stated terms), present what you find, and ask the user for a per-case decision. Adopt only on an explicit yes. ## Step 2 - Adopt and normalize (mechanical) Run the helper: ``` python3 plugins/bitranox/skills/meta-adopting-external-skills/adopt_skill.py [--name ] [--dest plugins/bitranox/skills] ``` It fetches the source (a shallow clone for a URL, a copy for a local path), runs the license gate first and aborts if it fails, normalizes the name to bitranox conventions, rewrites the skill's internal cross-references to `bitranox:`, scaffolds a `tests/` stub when the skill ships `.py`, records attribution (the credit line plus a `THIRD_PARTY_NOTICES.md` entry), runs the repo gate read-only, and prints a follow-up checklist. It never commits, never pushes, and never removes anything it did not write: a run that fails part-way removes the skill folder it started and puts `THIRD_PARTY_NOTICES.md` back, so a retry starts clean. Review every rewrite it reports. It renames the old name only where it identifies the skill: the front matter `name:`, an H1 that is exactly the name, a `:` reference, and a path segment under `skills/`. A plain word is never rewritten, because a skill named after its tool (`git`) uses that word for the tool (`git commit`); the report counts those mentions per file as "left for review" for you to judge. Its license gate reads every license that applies to what ships: every file of the skill's own folder (everything that gets copied), plus the license files, manifests and NOTICE of each folder above it up to the source root - never a sibling plugin's files, which govern that plugin, not this one. Within that scope it reads EVERY declared license - every license file (LICENSE, COPYING, LICENSE-*, LICENSES/*), every SPDX header, and every `license` / `license-files` value of every plugin.json, package.json, marketplace.json and pyproject.toml in any form (an SPDX expression, a `{text}` or `{file}` table, an npm `type` object, npm's `SEE LICENSE IN `, whose file it reads) - and one copyleft id rejects, including one alternative of an `OR`. Anything it cannot read, classify or vouch for (an unparseable manifest, a license text it does not recognise, an unknown id, a named license file that is missing, a symlinked folder or a link to a file outside the skill, whose target would be copied unread) stops it as NO LICENSE FOUND with the reason, for you to decide. Exit codes: 0 adopted, 1 the gate stopped it (nothing written), 2 error. ## Step 3 - Enhance to bitranox standards **REQUIRED: `bitranox:meta-skill-writer`.** Bring the adopted skill up to standard with it - RED/GREEN/REFACTOR, the description/CSO craft, token budget, cross-platform scripts, and real tests (replace the scaffolded stub with behaviour tests). Do not duplicate skill-writer here; follow it. ## Step 4 - Integrate and pass the gate Per `CONTRIBUTING.md`: the domains list in `bitranox:meta-using-bitranox-skills` is CATEGORIES plus exemplars, not a per-skill roster (the injected available-skills list is the source of truth for completeness, and `repo-gate.py` deliberately does not enforce the reverse direction) - so touch it ONLY if the new skill's prefix is not already covered by a category. Then bump `plugins/bitranox/.claude-plugin/plugin.json` one MINOR (a new skill), add a `CHANGELOG.md` entry that describes what the skill does (no provenance narrative), ship passing tests, and run the gate (`python3 plugins/bitranox/hooks/repo-gate.py --ci`). Attribution lives in the structured credit line and the `THIRD_PARTY_NOTICES.md` entry, never as prose history. The helper fills both from a ` (upstream)` placeholder; reword the credit line and the notice `Source:` field to the curated house style (e.g. `the superpowers plugin`; `Obra Superpowers plugin (URL)`) so a new entry reads like the existing ones. ## Step 5 - Upstream-first and coexist **REQUIRED: `bitranox:meta-self-improve`, its "Propagating skill (or hook) improvements upstream" section.** Offer the improvement to the original author first (a PR to their repo). Keep and ship the bitranox copy only if upstream stalls or declines. Either way the user's other installed plugins are left untouched - the bitranox copy coexists, and the user chooses which to invoke. ## Common mistakes - Doing any adoption work before the license check passes. - Assuming MIT when no license is present (it is all-rights-reserved). - Letting the helper or yourself commit, push, or uninstall anything. - Restating skill-writer or self-improve here instead of cross-referencing them. - Writing provenance narrative ("ported from X") instead of the structured credit line plus the notices entry. - Skipping the index/version/tests gate, so the change ships to no one.