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 port-one-shot bundles the safe single-skill porting ladder after source-shape recon confirms exactly one atomic prose package. It runs grammar/schema/checklist artifacts, source map, doctor, typed mechanical import, schema-derived shape crib, validate, imports check, deps check, scenario tests, compile, compact report, and optional direct-run estimated progress stats — all in one command. The command rejects parent folders with multiple SKILL.md files. Use the workspace flow for multi-skill or plugin-shaped roots, and the revision flow for existing reviewed skill.spec.yml files.
port-one-shot produces a reviewed scaffold, not a finished semantic spec. Missing scenario tests or unresolved dependency gaps are reported as review_required, not treated as passing proof. Do not install without completing the review obligations in the generated spec’s review_required: section.

​
Synopsis

skillspec port-one-shot <source> --out <dir> \
  [--target codex-skill|claude-skill|markdown] \
  [--prove] \
  [--force] \
  [--run-dir <dir>] \
  [--phase <id>] \
  [--requirement <id>] \
  [--json]

​
Options

FlagDescription
<source>Path to the single-skill source folder or SKILL.md file. Must resolve to exactly one atomic prose package.
--out <dir>Output directory for the generated spec, compile output, proof artifacts, and report.
--target codex-skill|claude-skill|markdownCompile target for the generated SKILL.md loader. Defaults to codex-skill.
--proveTreat failed required QA gates (validate, imports check, deps check, scenario tests) as a failed proof run. Exits non-zero when any required gate fails.
--forceOverwrite an existing skill.spec.yml draft in the output directory.
--run-dir <dir>Existing run directory for direct-run estimated progress stats. Used to record token metrics for the porting run.
--phase <id>Phase ID to scope the run-dir stats record.
--requirement <id>Requirement ID to scope the run-dir stats record. Repeatable for multiple requirements.
--jsonEmit the final report as JSON instead of human-readable text.

​
What the porting ladder bundles

port-one-shot runs the following steps in sequence and collects evidence for each:
StepWhat it does
Grammar artifactsEmbeds grammar/schema/checklist proof that the harness loaded the correct grammar version.
Source mapBuilds source-map.json and source-map.md for the source skill.
doctorRuns follow-through risk assessment and confirms simple_skill shape. Rejects if multiple SKILL.md files are found.
Typed mechanical importRuns import-skill to produce the draft skill.spec.yml, materialized code, and deps.toml.
Shape cribGenerates a schema-derived shape crib with schema-sensitive forms such as quoted YAML strings and artifact executable refs.
validateValidates the generated draft.
imports checkChecks declared local imports and load order.
deps checkChecks declared dependencies.
Scenario testsRuns scenario tests declared in the spec, if any. Missing tests are reported as review_required.
compileCompiles the validated spec to the requested target.
Compact reportWrites a port-one-shot.report.md with all gate results, proof paths, and review obligations.
Progress statsWhen --run-dir is supplied, appends estimated token metrics to the run directory.

​
Examples

Basic port to a Codex skill loader: 
skillspec port-one-shot ./source-skill \
  --out ./draft \
  --target codex-skill
Port with proof enforcement — exits non-zero if any required QA gate fails: 
skillspec port-one-shot ./source-skill \
  --out ./draft \
  --target codex-skill \
  --prove
Port and overwrite an existing draft: 
skillspec port-one-shot ./source-skill \
  --out ./draft \
  --target codex-skill \
  --force
Port with token metrics captured in a run directory: 
skillspec port-one-shot ./source-skill \
  --out ./draft \
  --target codex-skill \
  --prove \
  --run-dir .skillspec/traces/run-123 \
  --phase qa_and_proof \
  --requirement port_one_shot

​
--prove behavior

When --prove is set:
  • Each required QA gate (validate, imports check, deps check) must pass.
  • Scenario test failures or missing tests are reported as review_required (not fake proof).
  • If any required gate fails, the command exits non-zero regardless of other results.
  • Dependency gaps are reported as review_required, not suppressed.
Without --prove, gate failures are reported in the output but the command exits 0.

​
Git checkout and PR guidance

When the source is inside a local Git checkout, a successful run summary includes PR guidance. The recommended next steps are:
  1. Complete the review obligations in the generated spec’s review_required: section.
  2. Run skillspec validate, skillspec imports check, skillspec test, and skillspec deps check.
  3. Run skillspec install skill --target <target> --dry-run and review the planned writes.
  4. Install, restart the harness, and interact with the SkillSpec-backed skill through the agent.
  5. Open a PR with the generated contracts and proof artifacts against the source skill repo.
  • skillspec doctor <path> — Run a standalone follow-through risk assessment before porting.
  • skillspec import-skill <path> --out <path> — Run just the mechanical import step.
  • skillspec compile <path> --target <target> — Compile a reviewed spec independently.
  • skillspec workspace map <source-root> — Use for multi-skill or plugin-shaped roots.

Build docs developers (and LLMs) love

Get started for freeTalk to us