bh-rat/steer/converting-skills

converting-skills

Port an existing skill onto steer without changing what it does. The user gets a drop-in rebuild (same name, same triggers, same capabilities), a NOTICE.md recording every delta, and a measured comparison against the original instead of a vibe.

The conversion flow and lessons run on this skill's bundled runtime (scripts/steer.py); authoring the rebuild additionally needs the installed steer CLI, checked below.

Before you start

1. Check steer. Run steer --version. If it is missing, ask the

user to install it (uv tool install steer-ai or pip install steer-ai); do not hand-roll a lookalike scaffold.

1. Set two paths. SKILL is this skill's own directory (this

file's parent); WS is a scratch directory for this conversion.

1. Apply past lessons. Run

python3 "$SKILL/scripts/steer.py" learn show and follow what it says; those lessons came from real previous conversions.

1. Building something new instead? Creating a skill from scratch

or improving one you own is the building-skills skill's job, if installed; this one is for porting an existing skill faithfully.

Ground rules

• The prose is the payload. The source skill's rules, red-flag

lists, and phrasing are tuned content; convert the machinery around them and keep the voice verbatim.

• Rebuild exactly. Same name, same description triggers, same

capabilities. Anything you deliberately change goes in NOTICE.md.

• License is a gate, not a formality. Per skill, not per repo.

No-derivatives means stop and tell the user.

Process

The conversion runs behind an enforced flow: steps verify themselves against the conversion workspace, and you cannot skip ahead. The flow lives next to this file and operates on the conversion workspace:

python3 "$SKILL/scripts/steer.py" flow status --workspace "$WS" python3 "$SKILL/scripts/steer.py" flow next --workspace "$WS"

Lay the workspace out the way the flow verifies it:

original/ vendored copy of the source skill rebuild/<name>/ the steer rebuild out/conversion/ triage.md, comparison.md

The steps:

1. triage: inventory the original, identify its license, and map

each piece of hand-rolled machinery to a component (references/component-mapping.md, references/licensing.md). Everything lands in out/conversion/triage.md.

1. scaffold: steer new <original-name> --dir rebuild with exactly

the components triage mapped. Not more; a toolkit skill gets no flow, a knowledge skill may need no runtime components at all.

1. port: move the content, swap machinery for the generated

component instructions, put branch-only material behind references/ pointers, carry the license file, record every delta in NOTICE.md.

1. verify: steer validate rebuild/<name> gates the flow; fix

findings rather than arguing with them.

1. compare: measure both sides with

references/measuring.md and write out/conversion/comparison.md; present the deltas to the user.

Do NOT claim the conversion is done while python3 "$SKILL/scripts/steer.py" flow status --workspace "$WS" shows incomplete steps.

Learning

This skill improves with use. As you work:

• The moment the user corrects you, or something fails and then works a

different way, capture it: python3 "$SKILL/scripts/steer.py" learn note "<one imperative rule>" --kind correction Lessons are atomic rules ("Use X not Y when Z"), never secrets.

• When a lesson from python3 "$SKILL/scripts/steer.py" learn show

helped, run python3 "$SKILL/scripts/steer.py" learn confirm <id>; when one was wrong, python3 "$SKILL/scripts/steer.py" learn dispute <id>.

• Before finishing, record the outcome:

python3 "$SKILL/scripts/steer.py" learn run ok (or failed with --note).

If a learnings.md exists in this skill, read it too; those are promoted lessons that shipped with the skill.

References

Load these only when that step of the work is hit:

• Mapping hand-rolled machinery to components (triage, scaffold):

first read references/component-mapping.md.

• License identification and attribution artifacts (triage, port):

first read references/licensing.md.

• The comparison checklist (compare): first read

references/measuring.md.

Gotchas

• Well-built originals validate CLEAN. Do not promise "steer will find

errors"; the wins live in failure behavior, enforcement, secret hygiene, and context economy. Measure, then claim.

• Verify conditions need reality to check. Find the artifacts the

original's own prose already demands ("write it down") and make them files; use mandate steps only where no artifact exists.

• Moving files into references/ silently breaks their mentions of

each other; grep the moved files for cross-references and fix paths.

• Instructions in the original that print credential values (grepping

.env files, echoing tokens) leak secrets into the transcript. Convert to name-only detection, export by substitution, and persistence through the secrets component, and say so in NOTICE.md.

• Do not restate flow directives in the body or vice versa; directives

point at body sections, one source of truth.

• Remove scaffold directories the rebuild does not use (an empty

assets/ or references/) before validating; scripts/ stays, it holds the bundled runtime.