Skip to main content
skillspec import-skill creates a mechanical draft skill.spec.yml from a local SKILL.md file or single skill folder after source-shape recon confirms one atomic package. The generated draft is scaffolding, not a finished semantic port — it requires a human review pass to promote headings to rules, verify dependencies, and add scenario tests before the spec is trustworthy.
The generated draft is scaffolding. The importer extracts structure and evidence from prose, but it cannot infer routing rules, semantic decisions, or missing scenario tests. Do not use this output for proof or install without a complete review pass.

​
Synopsis

​
Options

​
What the importer produces

After a successful import the following artifacts are written alongside the generated spec:

​
Dependency inference

The importer builds dependency evidence from command blocks:
  • CLI deps — Inferred only from executable command evidence (shell/bash/zsh/console fenced blocks). Each accepted leading command token becomes a kind: cli dependency entry with a check field pointing back to the same command.
  • Python / JS / TS imports — Recorded as reference or example evidence in deps.toml, not as hard runtime dependencies. The review pass must complete the ledger.
  • Quarantine — Invalid prose-like candidates (Optional., TABLE, HTTP methods such as GET / POST, placeholders, private variable names) are quarantined in spec metadata rather than written as hard dependencies. Do not delete quarantine evidence to make QA pass.
A reviewed zero-dependency skill keeps dependency_count = 0; a byte-empty ledger is invalid.

​
When to use --source-map

For large or code-heavy source skills, run skillspec source map first, inspect source coverage, query nodes, dependencies, and code, then pass the fresh source-map.json:
The importer refuses stale source maps. Run skillspec source stale <source-map.json> to check freshness before passing one.

​
When NOT to use import-skill

​
Examples

Basic import from a single skill folder:
Import with a pre-built source map:
Import a single SKILL.md file directly:

​
After importing

The draft spec includes a review_required: section with the minimum review obligations:
  1. Review extracted headings and convert decision-heavy prose into rules:.
  2. Review command blocks and promote intentional ones to commands:.
  3. Review extracted resources and code snippets; promote only safe, intentional code into recipes.
  4. Review inferred command dependencies and add permission/provision choices.
  5. Review deps.toml with typed evidence; complete the ledger for quarantined entries.
  6. Add tests: (scenario tests) before trusting the structured skill.
Use skillspec grammar checklist --for import-skill to get the embedded coverage checklist for the semantic porting workflow before starting your review.
  • skillspec source map <path> — Build a source map for large or code-heavy skills before importing.
  • skillspec source stale <source-map.json> — Check whether a source map is stale before passing it to import-skill.
  • skillspec grammar checklist --for import-skill — Show the embedded coverage checklist for the import workflow.
  • skillspec grammar sensemake --view porting — Teach the grammar before importing so the harness understands spec constructs.
  • skillspec validate <path> — Validate the generated draft after reviewing it.