Skill new
Turn an authorized recurring task or selected L-NNN lesson into a useful skill draft,
using the existing scaffolding/01-foundation/TEMPLATE-skill.md from the trusted source.
The draft belongs to an explicitly owned path in the working target, not automatically
to Lintel's source bundle, a personal skill tree or a native discovery directory.
Drafting does not install, symlink, register or activate a skill. A bare canonical name
such as the proposed regen-mocks is distinct from a host wrapper li-<name> or
plugin spelling /li:<name>; do not silently strip or add a prefix.
When to use
- A
/li:lessons-addentry taggedskillify-candidateis mature enough to formalize - A repeating multi-step task has emerged in 3+ sessions
- Team-shared workflow needs a single command instead of step-by-step prose
- After
/li:capture --retrospectiveidentified a workflow worth standardizing
When NOT to use
- One-time task — overhead of skill authoring exceeds value
- Workflow that's still in flux — wait until shape stabilizes (3+ runs)
- Skill name conflicts with existing Lintel or upstream skill — resolve naming first
Inputs
- Required: bare canonical name (kebab-case), one-line description and authorized target directory
- Optional
--from-lesson <L-NNN>— read an existing lesson by ID, use it as seed --dir <subdir>— explicit repository-relative draft directory; no implicit personal destination- Optional
--voice <tier>— declared voice tier (default: internal; project/pack constraints still apply) - Optional
--cli <list>— source declarations using the accepted registry; default empty/unknown, not claimed host support - Optional
--tools <list>— tools the skill needs (default:Read, Bash)
Workflow
- Check scope and identity. Select the trusted source and working target separately. Use the catalog name/alias query below, not a private-tree scan or second inventory. Inspect only explicitly selected project-local draft/registration paths for additional collisions. A catalog miss covers that source namespace, not every installed plugin.
- Read the existing template and, only if requested, the exact
L-NNNlesson from the target's documented memory file. Print that block by ID withpython3 "$LINTEL_SOURCE_ROOT/bin/li-lessons.py" get --id L-NNN(exit 1 absent, 2 duplicated or malformed) and use its body, source and type as seed material. A missing seed is an unresolved input, not invented history. - Instantiate a valid opening header. Fill name, layer, description, color, tools, voice and cli_support. Keep declarations distinct from host observation and permissions. Use proper YAML quoting for supplied text; do not interpolate it into executable code.
- Retain the method. Turn the selected lesson into inputs, ordered steps, exclusions, expected output, failure/recovery behavior and at least two worked examples, including a negative case. Use actual available operations or explicit manual fallback. Leave unresolved logic marked TODO/DRAFT rather than promising it works. Query related names through the existing catalog and read only a genuinely selected reference.
- Write only the authorized new draft. Recheck destination ownership/nonexistence immediately before the host's file-edit operation. Refuse overwrite; an existing draft needs explicit revision authority. Do not run activation, global installation or symlinks.
- Validate that exact file with the existing validator below. Report its real scope, any invalid fields and remaining TODOs; inspect/test the method separately before adoption.
Check name and destination
Set skill_name to the literal canonical name and draft_relative to the explicitly
authorized target-relative .../SKILL.md. This preflight performs no writes.
set -euo pipefail
source_root="${LINTEL_SOURCE_ROOT:?select the trusted Lintel source}"
repo="${LINTEL_REPO_ROOT:?select the working target}"
: "${skill_name:?supply a nonempty canonical name}"
: "${draft_relative:?supply the owned target-relative SKILL.md path}"
python_cmd="${python_cmd:-python3}"
metadata=$("$python_cmd" -B "$source_root/bin/li-catalog.py" \
--json --kind=skill --name="$skill_name")
printf '%s' "$metadata" | "$python_cmd" -I -B -c '
import json, sys
result = json.load(sys.stdin)
if result["matched"]:
for entry in result["entries"]:
print("COLLISION: " + entry["id"] + " at " + entry["path"], file=sys.stderr)
sys.exit(2)
'
if [[ ! "$skill_name" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || [[ "$skill_name" == li-* ]]; then
printf 'INVALID: use a bare canonical kebab-case name, not a host wrapper; no automatic rename\n' >&2
exit 2
fi
"$python_cmd" -I -B - "$source_root/lib" "$repo" "$draft_relative" <<'PY'
import sys
from pathlib import Path
sys.path.insert(0, sys.argv[1])
from context_safety import checked_root, safe_path
from native_paths import native_io_path
try:
draft = safe_path(checked_root(Path(sys.argv[2])), sys.argv[3])
if draft.name != "SKILL.md" or native_io_path(draft).exists():
raise ValueError("target must be a new owned SKILL.md; refusing overwrite")
except (OSError, ValueError) as error:
print(f"INVALID destination: {error}", file=sys.stderr)
raise SystemExit(2)
print(draft)
PY
This uses the accepted source identity/alias and path contracts, not a new parser. Existence uses the accepted native I/O spelling of that same path; output stays logical. It does not grant ownership or make a later edit atomic; the host must still honor permissions and refuse a destination that appeared or changed before writing.
Validate the exact draft
Set draft to the file actually written, not the template or a whole installation.
set -euo pipefail
: "${LINTEL_SOURCE_ROOT:?select the trusted source}"
: "${draft:?select the actual draft file}"
source "$LINTEL_SOURCE_ROOT/lib/frontmatter.sh"
if validate_lintel_frontmatter "$draft" skill; then
printf 'DRAFT: opening frontmatter required fields present; method and semantic validation remain\n'
else
result=$?
printf 'INVALID draft: repair the reported frontmatter failures; no activation performed\n' >&2
exit "$result"
fi
The shared check verifies the opening block and required field presence, including
layer. It does not certify YAML types, allowed values, name uniqueness, executable
behavior or host compatibility. Those require their actual source checks and review.
install/verify.sh --frontmatter scans an installation; an extra filename does not
turn it into this per-draft check. If the helper is unavailable, leave validation unrun.
Report format
Skill draft: regen-mocks
Path: <authorized target>/drafts/regen-mocks/SKILL.md
Voice: internal
CLI declarations: <supplied registry IDs, or empty/unknown>
Tools: <declared operations, not proof of available bindings>
## Frontmatter validation
Catalog name/alias collision check: <actual result and source>
Opening-block required-field check: <actual command, exit and diagnostics>
Semantic metadata/method checks: <actual evidence, or NOT RUN>
## Body status
<remaining TODOs, unresolved inputs, worked and negative examples>
## Next steps
Review/test the draft's actual method in an owned fixture.
Adoption/discovery is a separately authorized adapter action, not performed here.
Failure modes
- Name/alias collides or metadata query fails: report the existing path or actual error, stop before writing. Do not auto-rename, drop an alias or replace failure with zero matches.
- Template missing or corrupted: report + exit. Do not silently generate without template.
- Destination exists, escapes the target or is not owned: refuse without changing it.
- Frontmatter validation fails after drafting: retain the owned draft as INVALID, with actual diagnostics; do not delete it, overwrite other work or advertise activation.
- Lesson id not found:
li-lessons.py getexits 1 (absent) or 2 (duplicated or malformed); report the missing input and use the real question channel if needed.
Examples
From a lesson:
> /li:skill-new --name regen-mocks --from-lesson L-042 --dir drafts/regen-mocks
[When that selected lesson exists and the target path is authorized]
Draft: drafts/regen-mocks/SKILL.md
Inputs: existing mock schema and explicit output directory.
Method: inspect the current generator, reproduce the drift, regenerate only owned mocks,
then compare the fixture and document failure recovery. Unknown tool bindings remain TODO.
Negative example: an absent schema stops before output; no empty "successful" mock set.
Validation: report the actual exact-file check; method not executed by this example.
Inline:
> /li:skill-new --name standup-brief --voice mixed --dir drafts/standup-brief
Description: "Summarize explicitly supplied commits and approved issue data."
Draft preserves input citations and separates completed work from blockers.
No network query or customer-data export follows from authoring the draft.
> /li:skill-new --name skill-router --dir drafts/skill-router
COLLISION: skill:skill-router is already canonical. No file written.
Aliases collide only when they are actually declared by the selected source. Retiring a historical alias makes that spelling available again; it does not retain an invisible reservation or automatically register a new command.
See also
TEMPLATE-skill.md— the scaffold this skill uses/li:lessons-add— records reusable patterns; oldskillify-candidatemetadata remains readable/li:doctor— broader diagnostics, not a substitute for exact-file validation/li:capture --retrospective— identifies skill candidates from actual session activity