[Feature]: Skill Importer bundle — ingest any SKILL.md into Spec Kit (Extensify workflow + bundle)

**Status:** Proposal
**Effort:** Low–Medium (≈90% assembly of existing primitives)
**Priority:** High — closes the emit↔ingest loop and makes Spec Kit the portable hub for the skills ecosystem

## Summary

Ship a **skill-importer bundle** that lets a user point Spec Kit at a directory, repo, or URL full of skills — **each a `SKILL.md` together with the scripts, references, assets, and templates it bundles in its enclosing directory** — and expose them **all** as native Spec Kit commands, automatically distributed to whichever of the 41 supported coding agents they use.

> **The unit of import is the whole skill directory, not just the markdown.** A `SKILL.md` typically references sibling files (`scripts/`, `references/`, `assets/`, templates); the importer must carry those along, and — because bundled scripts are **executable content** — treat them as a first-class part of the trust surface (see Trust & Compliance).

The capability is **mostly assembly of primitives that already exist**:

- **Extensify** (a community-catalog extension) already converts a single skill — a `SKILL.md` **plus every file/subdirectory in its enclosing directory** (`scripts/`, `references/`, `assets/`, templates) — into a Spec Kit extension (`create-extension-from-skill`), and already generates a `catalog.json` from a directory of extensions (`create-catalog`), with `validate-extension` / `validate-catalog` as QA.
- **Core** already renders commands → `SKILL.md` in skills mode (`agents.py:render_skill_command`, `_invocation_style.py`) and distributes to all agents via `CommandRegistrar`.
- **Bundles** already support `provides: {extensions, presets, steps, workflows}` (`bundler/models/manifest.py: COMPONENT_KINDS`).

The only genuinely new work is a **bulk discovery step** and a **workflow** that orchestrates the existing commands, packaged as a **bundle**.

---

## Problem Statement

I'm frustrated that **widely-used community agent-skills** live as **raw `SKILL.md` files spread across separate, independently-maintained repositories**, each **locked to one or two agents**, with **no one-step way to bring them into my project and my coding agent**. To use them today I copy/fork files by hand, they don't compose with each other, they carry no org context, no versioning, and no quality gate — and the moment upstream changes, my copy drifts.

The deeper motivation is **not just "import a file" — it's what a skill *becomes* once it's a Spec Kit command.** Spec Kit already has the composition, distribution, and governance machinery; a raw skill has none of it. Absorbing a `SKILL.md` into Spec Kit upgrades it from a static, single-agent prompt into a first-class, governed capability:

- **Multi-agent portability** — rendered to all 41 supported agents via skills mode, not locked to Claude Code.
- **Workflow orchestration** — the skill becomes a step that can be chained, gated, fanned-out, and sequenced in a Spec Kit workflow.
- **Preset layering** — org standards, compliance, and conventions overlay the skill via the preset composition algebra (prepend/append/wrap/replace over a named target) — **without forking upstream**.
- **Catalog hosting & distribution** — installable via `specify extension add`, discoverable, shareable through public or private catalogs.
- **Governance** — organizations vet and host approved skills in **private/internal catalogs**, with review gates and recorded **license + provenance** in each `extension.yml`.
- **Versioning** — skills become versioned extensions with update/rollback semantics, instead of a floating upstream file that silently drifts.
- **Validation / quality gate** — `validate-extension`/`validate-catalog` enforce a quality bar the raw skill never had.
- **Lifecycle-hook activation** — skills can be wired to SDD phases (before/after specify, plan, tasks, implement, …) for phase-aware, on-demand activation.
- **Reproducibility** — tag-pinned, bounded, offline-installable — no dependence on a moving remote file.
- **Stable, named contract** — the skill becomes a `/speckit-` command with deterministic invocation and (with the artifact/`--json` work) introspectable metadata.

This is the **"absorb, don't delegate"** thesis: Spec Kit doesn't merely coordinate with a skill — it *has* the skill, wrapped in orchestration, composition, distribution, and governance. That's the value the importer unlocks; the ingest step is just the on-ramp.

---

## Motivation

### Demand is proven at the very top of GitHub

Cross-referencing GitHub's **top-100 most-starred repositories** (`stars:>114000`, assessed 2026-09-10) against confirmed `SKILL.md` presence and license shows that **several of the most-starred repositories on GitHub are now `SKILL.md` skill collections** — instantly-citable, license-clean ingest sources:

| ⭐ | Repo | License | `SKILL.md` | Fit |
|---|---|---|---|---|
| 284K | [`obra/superpowers`](https://github.com/obra/superpowers) | MIT | 14 | Flagship methodology skills — golden-path demo |
| 258K | [`mattpocock/skills`](https://github.com/mattpocock/skills) | MIT | 38 | Reputable author, clean structure |
| 255K | [`affaan-m/ECC`](https://github.com/affaan-m/ECC) | MIT | 856 | Bulk-import showcase |
| 136K | [`Shubhamsaboo/awesome-llm-apps`](https://github.com/Shubhamsaboo/awesome-llm-apps) | Apache-2.0 | 9 | Curated agent-skills collection |
| 132K | [`garrytan/gstack`](https://github.com/garrytan/gstack) | MIT | 131 | Real-world curated Claude Code setup |
| 126K | [`nextlevelbuilder/ui-ux-pro-max-skill`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | MIT | 13 | Single high-value design skill |

Below the top-100 but strong: [`Fission-AI/OpenSpec`](https://github.com/Fission-AI/OpenSpec) (67K, MIT, 16).

### License gating is non-negotiable

Two of the **highest-profile** skill repos **cannot be legally ingested/redistributed** — the single most important design constraint:

| ⭐ | Repo | `SKILL.md` | Blocker |
|---|---|---|---|
| 175K | [`anthropics/skills`](https://github.com/anthropics/skills) | 20 | **No license** (all rights reserved) — canonical Agent Skills, yet un-ingestable |
| 74K | [`ComposioHQ/awesome-claude-skills`](https://github.com/ComposioHQ/awesome-claude-skills) | 854 | **No license** |

The importer **must** reject `NONE`/copyleft sources by default and surface the SPDX id, or it ships a legal liability.

### Format diversity (SKILL.md-first)

Not all skill content is `SKILL.md`: `f/prompts.chat` (prompts/CSV), `multica-ai/andrej-karpathy-skills` (`CLAUDE.md`), `VoltAgent/awesome-design-md` (`DESIGN.md`), `msitarzewski/agency-agents` (agent files). `SKILL.md` is the dominant, canonical format — ship that first; a normalization layer opens the door to others later.

---

## What already exists vs. what's new

| Capability | Where | Status |
|---|---|---|
| `SKILL.md` (single) → Spec Kit extension/command | Extensify `create-extension-from-skill` | ✅ exists (local path) |
| Directory of extensions → `catalog.json` | Extensify `create-catalog` | ✅ exists (bulk) |
| Validate extension / catalog | Extensify `validate-extension` / `validate-catalog` | ✅ exists |
| Command → `SKILL.md`, render to 41 agents | core `CommandRegistrar`, skills mode | ✅ exists |
| Bundle carrying extension + workflow + steps + preset | bundler `COMPONENT_KINDS` | ✅ supported |
| **Discover every `SKILL.md` in a tree** | — | ❌ **new** |
| **Fetch a remote source (repo/url) with provenance** | — | ❌ **new** |
| **License/compliance gate** | — | ❌ **new** |
| **Workflow orchestrating the above** | — | ❌ **new** |

Net-new code shrinks to: a **discovery step**, a **fetch/license-check step**, and a **workflow** — everything else is reuse.

---

## Proposed Solution

### 1. The workflow (`skills-to-catalog`)

The workflow **is** the bulk layer — `fan_out`/`fan_in` provide "for every skill" natively, so no new bulk *command* is required. (Field names below are illustrative, not the final schema.)

```yaml
workflow:
id: skills-to-catalog
steps:
- id: gather
type: init
# inputs: source (dir|repo|url), catalog_url, output_dir

- id: fetch
type: shell # remote clone/download — gated by shell-step opt-in (#2440/#2443)
when: "{{ source.is_remote }}"
# provenance: tag-pinned ref only (see #4185); bounded read

- id: license_gate
type: gate
# reject NONE / copyleft SPDX ids unless --allow-license explicitly set

- id: discover
type: shell # NEW: list every SKILL.md under the source tree
# emits: skills[] — each entry = the SKILL.md AND its enclosing directory (scripts/refs/assets)

- id: convert
type: fan_out
over: "{{ discover.skills }}"
steps:
- type: command # Extensify create-extension-from-skill (per skill)
- type: command # Extensify validate-extension
- type: gate # drop skills that fail validation

- id: assemble
type: fan_in
steps:
- type: command # Extensify create-catalog over generated dirs
- type: command # Extensify validate-catalog

- id: report
type: gate
# summary: N imported / M skipped (invalid) / K blocked (license); default output = LOCAL catalog for review
```

### 2. The bundle (`skill-importer`)

```yaml
# bundle.yml
bundle:
id: skill-importer
name: "Skill Importer"
provides:
extensions: [extensify] # the convert/catalog/validate commands
workflows: [skills-to-catalog] # the orchestration above
steps: [discover-skills] # the new custom discovery step (if not inlined as shell)
presets: [skill-import-defaults] # optional: strict-validate, output paths, license policy
```

One `specify bundle add skill-importer` installs the whole capability.

### 3. User story

> "Here's a repo full of skills — expose them all to Spec Kit and to the agent I use."

```
specify bundle add skill-importer
specify workflow run skills-to-catalog --source https://github.com/obra/superpowers@
# → validates + imports the MIT skills, writes a local catalog for review
specify extension catalog add ./catalog.json
specify extension add # rendered to Copilot/Claude/Cursor/… via --skills
```

---

## Trust & Compliance Model (the crux)

1. **License gate (hard requirement).** Read the source repo's SPDX license; **reject `NONE` and copyleft** (GPL/AGPL) by default. Surface the license in the import report. Require an explicit `--allow-license ` override to proceed. Record provenance + license in each generated `extension.yml`.
2. **Provenance / pinning.** Remote sources are fetched by **tag-pinned ref only** (reuse the `download_url` tag-pin policy, #4185); no `latest`/floating refs. Bounded reads throughout.
3. **Shell-step opt-in.** The fetch/discover shell steps inherit the existing **workflow shell-step opt-in** gate (#2440/#2443) — no silent code execution.
4. **Validate-as-gate.** `validate-extension` / `validate-catalog` run as **mandatory** `gate` steps; invalid/loose-frontmatter skills are flagged and skipped, never silently shipped. Bulk amplifies the loose-format problem, so this gate is essential.
5. **Bundled executable content.** A skill is imported **with its enclosing directory** (`scripts/`, `references/`, `assets/`, templates) — which can include **executable scripts**. Import copies and records these but **never runs them**; they are size-bounded, surfaced in the import report, and left for explicit review before any use. This is the largest reason the import is a trust boundary, not a plain file copy.
6. **Local-first, no auto-install.** Default output is a **local `catalog.json` the user reviews**; installing to the agent is a separate, explicit step.
7. **Attribution.** Preserve upstream author/source/license in the generated extension metadata.

---

## Fidelity & Limitations

- `SKILL.md` is a loose format; frontmatter conventions differ across ecosystems (Anthropic, Composio, etc.). The importer normalizes frontmatter but is **lossy for execution-harness skills** that assume a specific runtime — it imports **procedural/prompt content** cleanly, harness-coupled skills partially.
- The import unit is the **whole skill directory**: bundled `scripts/`, `references/`, `assets/`, and templates are carried into the generated extension (and mapped to `provides.scripts`/`provides.templates` where applicable). Skills whose scripts assume a specific host/runtime may need manual adjustment after import.
- Bulk conversion of hundreds of skills (e.g. ECC's 856) will surface quality variance — the validate gate + a per-import report set expectations.
- Non-`SKILL.md` formats (`CLAUDE.md`, `DESIGN.md`, agents, prompt CSVs) are **out of scope for v1**; the normalization layer is the future extension point.

---

## Delivery / Phasing

- **Phase 1 (v1):** discovery step + `skills-to-catalog` workflow + license/provenance gate, packaged as a **community bundle** (proving ground, like `sicario-spec`/`specassay`). Local-catalog output only.
- **Phase 2:** remote fetch with tag-pinned provenance; import report; preset defaults.
- **Phase 3:** promote to **first-party bundled** (shipped by default, still modular).

## Decomposition into Sub-Issues

This is best filed as an **umbrella / tracking issue**, then delivered through a set of **small, tightly-scoped, independently-reviewable sub-issues (and PRs)** — consistent with the project's small-PR / mega-PR-breakup norms and the per-filer throttle. Each sub-issue should stand on its own with its own acceptance criteria; none should depend on the whole landing at once. Candidate slices:

1. **Bulk skill discovery** — a step/utility that lists every `SKILL.md` under a local tree (no fetch, no convert).
2. **`skills-to-catalog` workflow** — orchestrate the existing Extensify commands (`fan_out` convert → `validate` gate → `fan_in` catalog), local sources only.
3. **License/compliance gate** — read source SPDX, block `NONE`/copyleft by default, explicit override + recorded acknowledgment; stamp license/provenance into generated `extension.yml`.
4. **Remote fetch with provenance** — tag-pinned clone/download as an opt-in shell step, bounded reads.
5. **Import report** — summarize imported / skipped-invalid / blocked-by-license, default output = local `catalog.json` for review.
6. **`skill-importer` bundle** — the `bundle.yml` packaging (extension + workflow + optional step/preset).
7. **Docs + example corpus** — golden-path (`obra/superpowers`) and bulk (`affaan-m/ECC` / `garrytan/gstack`) walkthroughs; cross-platform.
8. **First-party promotion** — move from community bundle to shipped-by-default (separate, later).
9. **(Stretch) format plugins** — normalization for `CLAUDE.md` / agent-file / prompt sources.

Scoping this way keeps each change reviewable, lets the security-sensitive slices (3, 4) get focused review, and allows the low-risk pieces (1, 2, 6, 7) to land independently.

## Acceptance Criteria

- [ ] `specify bundle add skill-importer` installs the Extensify extension + the `skills-to-catalog` workflow (and any custom step/preset it ships).
- [ ] Running the workflow against a **local** source discovers every `SKILL.md` in the tree and converts each **skill directory** (the `SKILL.md` + its bundled `scripts/`/`references/`/`assets/`/templates) to a Spec Kit extension, then validates them.
- [ ] Bundled **scripts are copied and recorded but never executed** during import; they're size-bounded and surfaced in the import report for review.
- [ ] Skills that fail validation (loose/invalid frontmatter) are **reported and skipped**, never written into the catalog.
- [ ] **Remote** sources are fetched **only by tag-pinned ref** (no floating/`latest`); bounded reads throughout.
- [ ] **License gate:** unlicensed (`NONE`) and copyleft sources are **blocked by default**; proceeding requires an explicit override with a recorded acknowledgment. The source SPDX id and provenance are recorded in each generated `extension.yml`.
- [ ] Default output is a **local `catalog.json` for review** — no automatic install to the agent.
- [ ] Imported skills render to **all supported agents** via skills mode (`--skills` / `CommandRegistrar`).
- [ ] Fetch/discover run as **opt-in shell steps** (inherit the workflow shell-step gate); no silent code execution.
- [ ] Documentation updated; works cross-platform (bash + PowerShell).

## Open Questions

- Should the discovery step be a first-class custom **step type** (reusable) or an inline `shell` step in the workflow?
- Do we want a thin convenience command (`specify skills import `) that wraps the workflow, or keep it workflow-only?
- License policy default: hard-block copyleft, or allow with a prominent warning + recorded acknowledgment?

---

## Alternatives Considered

- **Per-source bridge extensions (the current community pattern).** The community catalog already ships bridge extensions that each delegate to one upstream skill source — e.g. `superb` (Superpowers Bridge), `speckit-superpowers-bridge` (Superpowers Implementation Bridge), and `squad` (Squad Bridge). They work, but each couples Spec Kit to a specific upstream tool and must be authored and maintained **per source**; any source without a bespoke bridge is unreachable. A single generic importer absorbs **any** `SKILL.md` source into first-class Spec Kit extensions, so no per-source bridge is needed.
- **Manual copy/fork (today's default).** Copying skill files by hand gives none of the composition, versioning, validation, or multi-agent distribution above, and drifts from upstream.
- **A dedicated bulk `specify` command instead of a workflow.** Rejected for v1: the workflow's `fan_out`/`fan_in` already provide the bulk loop, so no new command surface is required (a thin convenience wrapper remains an open question).

---

## AI Assistance Disclosure

This issue was researched and drafted with AI assistance — GitHub Copilot (model: Claude Opus 4.8) — and was directed, reviewed, and edited by @mnriem, who understands and endorses the proposal. AI was used for the full initial draft and the supporting research (the top-100 star/license analysis and capability verification); all design decisions and final wording were reviewed by the human maintainer.

Start by reading Extensify's create-extension-from-skill, create-catalog, and validation commands, then inspect agents.py:render_skill_command, _invocation_style.py, and bundler/models/manifest.py: COMPONENT_KINDS. Map the existing workflow shell-step opt-in and tag-pin behavior before defining the discovery, fetch, license, and orchestration boundaries. Done means a bundle can produce a validated local catalog while reporting skipped, blocked, and imported skills without executing bundled scripts.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.