skillspec port-one-shot — Single Skill Porting Ladder

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

Flag	Description
`<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\|markdown`	Compile target for the generated SKILL.md loader. Defaults to `codex-skill`.
`--prove`	Treat failed required QA gates (`validate`, `imports check`, `deps check`, scenario tests) as a failed proof run. Exits non-zero when any required gate fails.
`--force`	Overwrite 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.
`--json`	Emit 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:

Step	What it does
Grammar artifacts	Embeds grammar/schema/checklist proof that the harness loaded the correct grammar version.
Source map	Builds `source-map.json` and `source-map.md` for the source skill.
`doctor`	Runs follow-through risk assessment and confirms `simple_skill` shape. Rejects if multiple SKILL.md files are found.
Typed mechanical import	Runs `import-skill` to produce the draft `skill.spec.yml`, materialized code, and `deps.toml`.
Shape crib	Generates a schema-derived shape crib with schema-sensitive forms such as quoted YAML strings and artifact executable refs.
`validate`	Validates the generated draft.
`imports check`	Checks declared local imports and load order.
`deps check`	Checks declared dependencies.
Scenario tests	Runs scenario tests declared in the spec, if any. Missing tests are reported as `review_required`.
`compile`	Compiles the validated spec to the requested target.
Compact report	Writes a `port-one-shot.report.md` with all gate results, proof paths, and review obligations.
Progress stats	When `--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:

Complete the review obligations in the generated spec’s review_required: section.
Run skillspec validate, skillspec imports check, skillspec test, and skillspec deps check.
Run skillspec install skill --target <target> --dry-run and review the planned writes.
Install, restart the harness, and interact with the SkillSpec-backed skill through the agent.
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.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec port-one-shot — Single Skill Porting Ladder

Synopsis

Options

What the porting ladder bundles

Examples

`--prove` behavior

Git checkout and PR guidance

​Synopsis

​Options

​What the porting ladder bundles

​Examples

​--prove behavior

​Git checkout and PR guidance

​Related commands

Synopsis

Options

What the porting ladder bundles

Examples

`--prove` behavior

Git checkout and PR guidance

Related commands