Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt

Use this file to discover all available pages before exploring further.

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

skillspec import-skill <path> --out <path> [--source-map <path>]

​
Options

FlagDescription
<path>Path to the SKILL.md file or single-skill folder to import.
--out <path>Output path for the generated skill.spec.yml.
--source-map <path>Path to a pre-built source-map.json from skillspec source map. Required for large or code-heavy sources; the importer refuses stale maps.

​
What the importer produces

After a successful import the following artifacts are written alongside the generated spec:
ArtifactPurpose
source/SKILL_md.oldOriginal prose skill preserved under a non-discoverable, non-Markdown filename so it is not re-indexed as a harness skill.
resources/imported-code/Fenced code blocks materialized as individual files and referenced from the draft spec’s code: section.
deps.tomlDependency evidence ledger declaring CLI dependencies, reference evidence from package imports, and quarantine entries.
imports/Non-SKILL.md Markdown documents from the source folder materialized as package-local on-demand imports.

​
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: 
skillspec source map ./source-skill --out ./draft/.skillspec/source-map
skillspec source coverage ./draft/.skillspec/source-map/source-map.json
skillspec import-skill ./source-skill \
  --out ./draft/skill.spec.yml \
  --source-map ./draft/.skillspec/source-map/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

SituationUse instead
Parent folder with multiple SKILL.md files, cross-skill references, or plugin markersskillspec workspace map to identify atomic packages and dependency edges first
Existing reviewed skill.spec.ymlRevision path — do not re-import; edit the existing spec
GitHub URI sourceskillspec source stage <uri> to stage first, then import from the staged path

​
Examples

Basic import from a single skill folder: 
skillspec import-skill ./source-skill --out ./draft/skill.spec.yml
Import with a pre-built source map: 
skillspec import-skill ./source-skill \
  --out ./draft/skill.spec.yml \
  --source-map ./draft/.skillspec/source-map/source-map.json
Import a single SKILL.md file directly: 
skillspec import-skill ./source-skill/SKILL.md --out ./draft/skill.spec.yml

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us