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.

Importing and porting are two sides of the same job. Importing means creating a mechanical skill.spec.yml scaffold from your existing SKILL.md — extracting commands, code blocks, and dependency mentions, and preserving prose as evidence. Porting means completing that scaffold: promoting prose routes into structured rules, verifying dependencies, writing scenario tests, and compiling a thin loader. The important thing to understand is that import is the start of contract creation, not the end. The generated draft is scaffolding, not a finished behavioral contract. port-one-shot bundles the entire ladder into a single command when you have exactly one atomic prose skill package. For multi-skill or plugin-shaped workspaces, or when you need to debug a specific gate, the manual step-by-step path gives you full control.

​
Quick Path: Port-One-Shot

For a single SKILL.md folder, run: 
skillspec port-one-shot ./my-skill --out ./draft --target codex-skill --prove
port-one-shot rejects parent folders with multiple SKILL.md files. Use the workspace flow for those cases.
The command runs the following gates in order and reports the result of each:
  1. Grammar / schema / checklist artifacts — writes grammar-porting.md, grammar-checklist.md, schema.json, and shape-crib.yml to ./draft/.skillspec/port/ so the harness can reference the current grammar without loading from memory.
  2. Source map — builds source-map.json and source-map.md in ./draft/.skillspec/source-map/ using Markdown AST positions for exact span tracking.
  3. Doctor report — runs a full risk assessment and writes doctor.json as the baseline.
  4. Typed mechanical import — creates ./draft/skill.spec.yml from the source, preserving prose as source/SKILL_md.old, materializing fenced code under resources/imported-code/, and writing deps.toml.
  5. Validate — parses and validates the draft spec against the typed grammar.
  6. Imports check — validates declared local imports, sections, and dependency-first load order.
  7. Deps check — checks declared dependencies. Gaps are reported as review_required, not suppressed.
  8. Scenario tests — runs any tests declared in the spec. Missing tests are reported as review_required rather than treated as passing.
  9. Compile — compiles the spec into the target format (here codex-skill).
  10. Optional proof — with --prove, records estimated progress stats to the run directory.
The overall status is passed, passed_with_review_required, or failed. review_required items are preserved in the output for the review pass — they are not fake proof of completion.If the source is inside a local Git checkout, successful summaries include PR guidance so the generated contract can be proposed back to the source skill repository.
Available --target values are codex-skill, claude-skill, and markdown. If ./draft/skill.spec.yml already exists, add --force to overwrite.

​
Step-by-Step Manual Path

Use the manual path when you need to inspect an individual gate, build a custom import flow, or port a skill from a public GitHub URI.
1

Build the source map

skillspec source map ./my-skill --out ./draft/.skillspec/source-map
This builds source-map.json and source-map.md from the prose skill using Markdown AST positions. The source map lets you and the harness query exact source spans, dependency mentions, code blocks, and coverage before importing — so the importer has evidence to work from rather than guessing.For a public GitHub skill, pass the URL directly:
skillspec source map https://github.com/owner/repo/tree/main/skills/pdf \
  --out ./draft/.skillspec/source-map
The command reports source_path for the staged local source, which you use in subsequent commands. After mapping, inspect coverage:
skillspec source coverage ./draft/.skillspec/source-map/source-map.json
skillspec source query ./draft/.skillspec/source-map/source-map.json nodes --view index
skillspec source query ./draft/.skillspec/source-map/source-map.json dependencies --view summary
2

Run a Doctor baseline

skillspec doctor ./my-skill
Capture the baseline risk score, findings, and likely consequence before any changes. Publish this report alongside the generated contract so reviewers can see both the original skill risk and the proof after porting. Save the JSON for CI:
skillspec doctor ./my-skill --json > ./draft/.skillspec/port/doctor-baseline.json
3

Import the skill

skillspec import-skill ./my-skill \
  --out ./draft/skill.spec.yml \
  --source-map ./draft/.skillspec/source-map/source-map.json
The importer reads the source map (refusing stale maps) and creates a mechanical draft. It preserves the original prose as source/SKILL_md.old, materializes fenced code under resources/imported-code/, writes deps.toml, and adds review_required notes wherever semantic review is required.The generated applies_when, entry, routes, rules, states, elicitations, trace, recipes, closures, proof, and tests fields are intentionally empty scaffolds. The importer cannot prove that prose instructions have become correct routing rules, bounded questions, or scenario tests — that promotion is the real authoring work.
4

Review the draft

Open ./draft/skill.spec.yml in your editor. Focus the review on:
  • Which paragraphs describe route choices? Promote them into routes and rules.
  • Which phrases are hard constraints? Move them to forbid in a rule or entry policy.
  • Which phrases describe bounded questions? Create elicitations.
  • Which command blocks are templates versus examples? Classify and add safety classes.
  • Which dependencies were inferred correctly and which need permission or provision choices?
  • Which review_required notes remain? Each one is an unproven promotion obligation.
Do not delete dependency evidence to make QA pass. If a required dependency is absent, record it as missing, deferred, or required_but_unproven in deps.toml. The final proof is partial until that dependency-backed workflow is actually proven.
5

Validate the spec

skillspec validate ./draft/skill.spec.yml
Parses and validates the spec against the typed grammar, parser checks, identifiers, and cross-references. Fix any errors before proceeding — the remaining QA gates depend on a valid spec.
6

Check imports

skillspec imports check ./draft/skill.spec.yml
Validates declared local imports, sections, and dependency-first load order. Exits non-zero if any import is missing, has an invalid path, or requests a section that does not exist in the imported file.
7

Check dependencies

skillspec deps check ./draft/skill.spec.yml
Checks declared dependencies for the whole spec. Local checks can pass or fail; harness-specific checks are reported as deferred. Use --command <id> to check a single command’s dependency requirements:
skillspec deps check ./draft/skill.spec.yml --command validate_spec
8

Run scenario tests

skillspec test ./draft/skill.spec.yml
Runs scenario tests declared in the spec against the decision engine. An imported scaffold with no declared tests will report zero tests — that is a review_required signal, not a passing signal. Add at least one test per route before treating the skill as trusted.

​
Reviewing the Draft

The importer generates several artifacts alongside skill.spec.yml that are part of the contract package, not just build intermediates:

source/SKILL_md.old

The original prose, preserved as non-discoverable evidence. Deliberately not named SKILL.md or .md so it cannot be loaded as a second active skill. Use it as the source of truth when promoting routes and rules.

resources/imported-code/

Fenced code blocks materialized as package-local files with provenance attached. Review each block: classify it as an example, a runnable script, a probe, or a transform before promoting to a recipe.

deps.toml

The dependency ledger scaffold. Every entry should record source authority, local status, install risk, proposed provision command, required workflows, and degraded proof impact. A reviewed zero-dependency skill keeps deps.toml with dependency_count = 0; a byte-empty ledger is not valid proof.

routes and rules (scaffolded)

Empty scaffolds for applies_when, entry, routes, rules, states, elicitations, trace, recipes, closures, proof, and tests. These are the real authoring targets.

​
What review_required Means

The importer marks uncertain promotions with review_required notes in the spec. These notes survive validation — a spec can be valid and still carry review_required items. Each review_required note is an obligation: a specific behavioral question that the source prose raises but the importer could not prove. For example, a note might flag that a route was inferred from a heading pattern but the actual routing condition was not deterministic enough to generate a rule predicate. Until review_required items are resolved — either by promoting the behavior into structured fields or by explicitly recording why it was deferred — the skill’s behavioral contract is incomplete. skillspec port-one-shot reports passed_with_review_required rather than passed when any items remain.
Do not delete dependency evidence to make QA pass. If deps check reports a gap, the correct response is to complete deps.toml with source authority, local status, install risk, and degraded proof impact — not to remove the dependency entry. A byte-empty deps.toml is not valid proof that dependencies were reviewed. Deleting evidence manufactures a false pass and leaves the skill’s runtime behavior unproven.
For a full field reference covering every skill.spec.yml section — routes, rules, elicitations, dependencies, imports, resources, code, artifacts, recipes, commands, states, closures, proof, and tests — see the spec grammar reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us