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

Bắt đầu bằng cách đọc các lệnh create-extension-from-skill, create-catalog và validation của Extensify, sau đó kiểm tra agents.py:render_skill_command, _invocation_style.py và bundler/models/manifest.py: COMPONENT_KINDS. Lập bản đồ hành vi hiện có của việc opt-in workflow shell-step và ghim tag trước khi xác định ranh giới discovery, fetch, cấp phép và orchestration. Hoàn tất có nghĩa là một bundle có thể tạo ra một catalog cục bộ đã được validation, đồng thời báo cáo các skill bị bỏ qua, bị chặn và được import mà không thực thi các script đi kèm 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-<name> 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	MIT	14	Flagship methodology skills — golden-path demo
258K	mattpocock/skills	MIT	38	Reputable author, clean structure
255K	affaan-m/ECC	MIT	856	Bulk-import showcase
136K	Shubhamsaboo/awesome-llm-apps	Apache-2.0	9	Curated agent-skills collection
132K	garrytan/gstack	MIT	131	Real-world curated Claude Code setup
126K	nextlevelbuilder/ui-ux-pro-max-skill	MIT	13	Single high-value design skill

Below the top-100 but strong: 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	20	No license (all rights reserved) — canonical Agent Skills, yet un-ingestable
74K	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.)

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)

# 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@<tag>
# → validates + imports the MIT skills, writes a local catalog for review
specify extension catalog add ./catalog.json
specify extension add <skill>            # 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 <spdx> 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 <source>) 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.