armelhbobdad/oh-my-skills / .claude/skills/skf-create-skill
skf-create-skill
VerifiedCompile a skill from a brief. Supports --batch for multiple briefs. Use when the user requests to "create a skill" or "compile a skill."
references/validate.md
View on GitHub---
nextStepFile: 'generate-artifacts.md'
# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
# (installed SKF module path first, src/ dev-checkout fallback); first existing
# path wins. HALT (exit code 3, helper-missing) if neither resolves: the
# staging-directory artifacts this step writes need atomic writes.
atomicWriteProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
- '{project-root}/src/shared/scripts/skf-atomic-write.py'
# Resolve `{descriptionGuardHelper}` by probing `{descriptionGuardProbeOrder}`
# in order (installed SKF module path first, src/ dev-checkout fallback);
# first existing path wins. HALT (exit code 3, helper-missing) if neither
# resolves: letting an external tool's rewrite of the description field
# stand would silently regress discovery quality.
descriptionGuardProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-description-guard.py'
- '{project-root}/src/shared/scripts/skf-description-guard.py'
# Resolve `{hashContentHelper}` by probing `{hashContentProbeOrder}` in order
# (installed SKF module path first, src/ dev-checkout fallback); first existing
# path wins. Advisory: if neither resolves, §2 hashes nothing and reports that
# SKILL.md may have been rewritten (not hashed) by skill-check --fix.
hashContentProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
- '{project-root}/src/shared/scripts/skf-hash-content.py'
# Resolve `{frontmatterValidator}` by probing `{frontmatterValidatorProbeOrder}`
# in order (installed SKF module path first, src/ dev-checkout fallback); first
# existing path wins.
# HALT (exit code 3, helper-missing) if neither resolves: §6's description
# check has no fallback, and §0's post-restore re-validation hook uses it
# too; an installed module has no src/ tree, so a bare src/ path would
# silently skip both.
frontmatterValidatorProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
- '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
# Resolve `{shardBodyHelper}` by probing `{shardBodyProbeOrder}` in order
# (installed SKF module path first, src/ dev-checkout fallback); first existing
# path wins. §4 uses it as the deterministic selective splitter and reads its
# `tier1_preserved` field instead of counting Tier-1 headings pre/post by hand.
shardBodyProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-shard-body.py'
- '{project-root}/src/shared/scripts/skf-shard-body.py'
# Resolve `{renderMetadataStatsHelper}` by probing `{renderMetadataStatsProbeOrder}`
# in order (installed SKF module path first, src/ dev-checkout fallback); first
# existing path wins. §7 uses it in --check mode to re-derive the metadata
# `stats` / `confidence_distribution` instead of re-doing the arithmetic by hand.
renderMetadataStatsProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-render-metadata-stats.py'
- '{project-root}/src/shared/scripts/skf-render-metadata-stats.py'
# Resolve `{verifyProvenanceCompletenessHelper}` to the first existing path.
# §7's relabel runs its `kind-at`, and §7a its `verify` and `fix`. Advisory:
# if neither path resolves, §7a records that its check did not run, and a
# node kind that needs `kind-at` stays a WARN.
verifyProvenanceCompletenessProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-verify-provenance-completeness.py'
- '{project-root}/src/shared/scripts/skf-verify-provenance-completeness.py'
# Resolve `{tesslReviewHelper}` by probing `{tesslReviewProbeOrder}` in order
# (installed SKF module path first, src/ dev-checkout fallback); first existing
# path wins. If neither path exists, §6b records that Tessl Review did not run
# and continues: the review is optional and never gates the workflow.
tesslReviewProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-tessl-review.py'
- '{project-root}/src/shared/scripts/skf-tessl-review.py'
# Resolve `{tesslReviewRules}` the same way. §6b loads it after a completed
# review to mark the suggestions SKF does not follow; without it the
# suggestions are listed unmarked.
tesslReviewRulesProbeOrder:
- '{project-root}/_bmad/skf/shared/references/tessl-review.md'
- '{project-root}/src/shared/references/tessl-review.md'
preferencesFile: '{sidecar_path}/preferences.yaml'
# Loaded only when §7 or §7a meets a provenance label or node-kind finding.
relabelRuleData: 'references/relabel-rule.md'
# Resolve `{extractionPatternsData}` to the first existing path, as step 3
# did: the Relabel Rule's `kind-at` reads the recipes there.
extractionPatternsDataProbeOrder:
- '{project-root}/_bmad/skf/skf-create-skill/references/extraction-patterns.md'
- '{project-root}/src/skf-create-skill/references/extraction-patterns.md'
# Resolve `{securityScanHelper}` by probing `{securityScanProbeOrder}` in
# order (installed SKF module path first, src/ dev-checkout fallback); first
# existing path wins. If neither path exists, §5 records the scan as
# skipped and continues: the scan is optional and never gates the workflow.
securityScanProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-security-scan.py'
- '{project-root}/src/shared/scripts/skf-security-scan.py'
# HARD HALT helpers (Rules).
sourceTreeProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-source-tree.py'
- '{project-root}/src/shared/scripts/skf-source-tree.py'
emitEnvelopeProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
- '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
---
<!-- Config: communicate in {communication_language}. -->
# Step 6: Validate
## STEP GOAL:
To validate the compiled SKILL.md content against the agentskills.io specification using skill-check, auto-fix any validation failures, confirm that the frontmatter description holds no angle brackets, and confirm spec compliance before artifact generation. When the user has opted in to Tessl Review, also record Tessl's review of the skill as advice; it never gates the step.
## Rules
- Focus only on validating compiled content against spec — only fix spec compliance issues
- Validation and auto-fix modify files in the staging directory
- `<staging-skill-dir>` resolves to `_bmad-output/.skf-stage/{skill-name}/` as created by step 5. Its last folder name must match the skill's frontmatter `name` field exactly — `skill-check`'s `frontmatter.name_matches_directory` rule rejects any suffix.
- If skill-check unavailable: skip validation, add warning to evidence report
- For the validation verdict, ignore non-zero exit codes from skill-check if JSON output shows 0 errors; the security scan's row follows the result `skf-security-scan.py` prints (§5)
- Tessl Review (§6b) is optional and advisory: it never halts, never asks the user anything and never changes the staged files, and SKF applies none of its suggestions
- A HARD HALT, once step 3 §2b has bound `{source_tree}`, first runs `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` (resolved from `{sourceTreeProbeOrder}`) and goes on whatever it prints, and emits through `{emitEnvelopeHelper}`, resolved from `{emitEnvelopeProbeOrder}` when it is not bound. After its envelope, under `--batch` it ends only this brief: return to `references/batch-mode.md` §3, even when the halt reads as the end of the run.
## MANDATORY SEQUENCE
**Helpers.** Resolve `{atomicWriteHelper}`, `{descriptionGuardHelper}` and `{frontmatterValidator}` now, each ← the first existing path of its probe order. If one has no path, **HARD HALT** (exit code 3, `helper-missing`, phase `validate`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Cannot validate the staged skill: {the missing script} is missing. Re-install SKF, then re-run create-skill."
### 0. Description Guard Protocol
**Used by:** §2 (`skill-check check --fix`) and §4 (the body split).
The deterministic phases are executed via `{descriptionGuardHelper}`: the calling sections (§2 and §4) invoke the helper at the capture and verify-restore points.
**Guard outputs.** Each `capture` writes the description it reads from the staged `<staging-skill-dir>/SKILL.md`, just before the tool that may rewrite it, to `{run_dir}/description-guard.json`, and each `verify-restore` reads it there with `--captured-file`, so the description never passes through a shell string. Bind `{guarded_description}` ← that file's `description`. Bind `{guard_restored}` ← `restored` and `{guard_diff_kind}` ← `diff_kind` from each `verify-restore`. When `{guard_restored}` is true, set the in-context `description` to `{guarded_description}` so later sections do not work from the tool-mutated value, and record `description_guard_restored: true` with the tool name and `description_guard_diff_kind: {guard_diff_kind}` in workflow context for the evidence report (§8). A later `verify-restore` that exits 0 with `{guard_restored}` false leaves those records in place.
**Empty-snapshot rule.** `verify-restore` refuses an empty or whitespace-only description in `{run_dir}/description-guard.json`, and a file it cannot read (exit 1, file untouched). Never re-run it with the empty value: writing it back would blank the field the guard protects. If the description compile §2a sanitized is still in context (an in-context copy of the description, not of the file), re-run `verify-restore` with that value: write `{"description": <that value as a JSON string>}` to `{run_dir}/description-guard.json` with a file write, never `echo` (the value can hold quotes, `$` or backticks), and run the same `verify-restore` line again, once. Otherwise, or when that re-run exits 1 too, record `description_guard_restored: false` and `description_guard_refused: empty-capture` with the tool name; the evidence report (§8) renders that as a fired guard, not as a clean run.
**This skill's post-restore re-validation hook:** after `{descriptionGuardHelper}` reports `restored: true`, resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins), run `uv run {frontmatterValidator} <staging-skill-dir>/SKILL.md` and capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field, flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step 9 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
### 1. Check Tool Availability
Run: `timeout 30s npx skill-check -h` — the short timeout protects against a cold `npx` download blocking the workflow indefinitely on a slow network.
- If succeeds: Continue to automated validation (section 2)
- If fails or times out: Perform manual fallback (section 3); add note to evidence-report: "Spec validation performed manually: skill-check tool unavailable". Also set `metadata.validation_status: 'manual-only'` in `metadata.json` (write via `python3 {atomicWriteHelper} write --target <staging-skill-dir>/metadata.json`), and in the evidence-report's `Validation Results` section mark the Body row explicitly as `skipped: skill-check unavailable` (§5, §6 and §6b do not depend on skill-check). Downstream consumers (pipeline, forger, test-skill) check `validation_status` to decide how much weight to put on the artifact; leaving it unset would make a manual-only run look equivalent to a fully automated PASS.
**Important:** Do not assume availability — empirical check required.
### 2. Validate & Auto-Fix (skill-check check --fix)
Run the external skill-check tool against the compiled skill staging directory.
**Flag probe (run once, cache the result for §4's re-validation):**
```bash
npx skill-check check --help 2>/dev/null | grep -- --no-security-scan
```
- If the probe matches `--no-security-scan`: set `{security_scan_flag} = "--no-security-scan"`.
- Else run a second probe — `npx skill-check check --help 2>/dev/null | grep -- --skip-security` — and if it matches, set `{security_scan_flag} = "--skip-security"`.
- If neither flag exists: set `{security_scan_flag} = ""` (empty) AND set `{skill_check_flag_fallback} = true`. Skip §2 and §4 automated flows entirely — fall through to §3 manual frontmatter validation. Record in evidence-report: `skill_check_flag_probe: neither --no-security-scan nor --skip-security supported by installed skill-check; validation performed manually`.
**If a security-scan-disable flag was resolved (probe succeeded):** run the `skill-check check --fix` call where the Description Guard block below holds it (its Phase 2), never before that block's first `hash` and its `capture`.
This performs frontmatter validation, description quality checks, body limit enforcement, local link resolution, file formatting, auto-fix of deterministic issues, and quality scoring (0-100) across five weighted categories.
**Parse the JSON output** of the Phase 2 call below for: `scores[].score` (0-100; match the entry by `relativePath`/`skillId`; falls back to a top-level `qualityScore` on older skill-check builds) and `diagnostics[]` (remaining issues). skill-check's JSON lists no fix: the two `hash` calls below tell whether `--fix` changed SKILL.md.
**Description Guard Protocol:** This invocation may modify SKILL.md. Wrap the `skill-check check --fix` call in the four-phase guard defined in §0 by invoking `{descriptionGuardHelper}` at the capture and verify-restore points, and hash SKILL.md with `{hashContentHelper}` (resolve it ← first existing path in `{hashContentProbeOrder}`) before the capture and after the verify-restore:
```bash
# Before the guard: hash SKILL.md
uv run {hashContentHelper} hash <staging-skill-dir>/SKILL.md
# stash the returned `content_hash` as `skill_md_hash_before`
# Phase 1: capture before the tool call
uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md > "{run_dir}/description-guard.json"
# the snapshot lands in the run folder; read its `description` as `guarded_description`
# Phase 2: run skill-check
npx skill-check check <staging-skill-dir> --fix --format json {security_scan_flag}
# Phases 3+4: verify and restore after the tool call
uv run {descriptionGuardHelper} verify-restore <staging-skill-dir>/SKILL.md \
--captured-file "{run_dir}/description-guard.json"
# After the guard: hash SKILL.md again
uv run {hashContentHelper} hash <staging-skill-dir>/SKILL.md
# stash the returned `content_hash` as `skill_md_hash_after`
```
If `restored: true` in the verify-restore output, apply §0's post-restore re-validation hook. Step 7 promotes the staged files as they are on disk, `--fix` changes included.
Run the second `hash` call after the last `verify-restore`, a §0 re-run included. When `skill_md_hash_before` and `skill_md_hash_after` differ, record `skill_check_fix_changed: true` for §8. When no `{hashContentProbeOrder}` path exists (skip both `hash` calls) or a `hash` call prints no `content_hash`, record `skill_check_fix_changed: unchecked` whatever the other call printed, so §8 says SKILL.md may have been rewritten.
**Note:** `skill-check` may return non-zero exit code even when `summary.errorCount` is 0. Always rely on parsed JSON, not the shell exit code.
- **Score ≥ 70:** Record "Schema: PASS (score: {score}/100)" in evidence-report
- **Score < 70:** Log remaining diagnostics as warnings, record "Schema: WARN — score {score}/100, {count} remaining issues", proceed
- **Unfixable errors:** Record specific rule IDs and suggestions, proceed with warnings
### 3. Validate Frontmatter (Fallback)
**If skill-check was available:** Skip — already validated in step 2.
**If skill-check not available (fallback):** Perform manual frontmatter compliance check:
- [ ] Frontmatter present — file starts with `---` and has closing `---`
- [ ] `name` field — present, non-empty, lowercase alphanumeric + hyphens only, 1-64 chars
- [ ] `name` matches skill output directory name
- [ ] `description` field — present, non-empty, 1-1024 characters
- [ ] No unknown fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` permitted
- [ ] `version` and `author` are not in frontmatter (they belong in metadata.json)
If fails: auto-fix (deterministic), re-validate once, record result. If passes: record "Frontmatter: PASS".
### 4. Split Oversized Body (if needed)
**If step 2 reported `body.max_lines` failure:** split the body with `{shardBodyHelper}`, the splitter step 5b auto-shard runs (resolve it from `{shardBodyProbeOrder}`; first existing path wins), inside the §0 guard, since a split may rewrite the frontmatter. Never run `npx skill-check split-body --write`: it moves every `##` section to `references/`, Tier 1 included.
```bash
# Phase 1: capture before the split
uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md > "{run_dir}/description-guard.json"
# the snapshot lands in the run folder; read its `description` as `guarded_description`
# Phase 2: the split
uv run {shardBodyHelper} <staging-skill-dir>/SKILL.md --budget 400
# Phases 3 and 4: verify and restore after the split
uv run {descriptionGuardHelper} verify-restore <staging-skill-dir>/SKILL.md \
--captured-file "{run_dir}/description-guard.json"
```
If `restored: true` in the verify-restore output, apply §0's post-restore re-validation hook.
The splitter extracts the Tier 2 sections, those whose heading starts `## Full`, largest first, to `references/` until the body fits, puts a cross-reference blockquote in each one's place, and reports `sections_extracted`, `body_lines_after`, `tier1_preserved` (with any pulled heading in `tier1_missing`), `xref_ok` and `under_budget`. Act on them:
- **`tier1_preserved` is false:** **HARD HALT** (exit code 5, `tier1-not-preserved`, phase `validate`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Split reduced Tier-1 section count (missing {tier1_missing}). Tier-1 sections must remain inline. Aborting the body split: manual review required." Every Tier 1 section must remain inline, and the context snippet's `#quick-start` and `#key-types` anchors name two of them, so this one check keeps the anchors resolving too.
- **`xref_ok` is false:** **HARD HALT** (exit code 5, `shard-xref-broken`, phase `validate`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "The body split left a cross-reference that does not resolve. Aborting."
- **`under_budget` is false** (rare: Tier 1 alone runs past about 300 lines): trim `## Key API Summary` and `## Architecture at a Glance` until the body fits, never moving a Tier 1 section to `references/`, then run the split again, guard included, and take `body_lines_after` from it.
Then re-validate: `npx skill-check check <staging-skill-dir> --format json {security_scan_flag}`, with the flag cached from §2's probe. If `{skill_check_flag_fallback}` is true, skip re-validation and rely on the §3 manual check.
**If skill-check unavailable or no body size issue:** Skip.
**Score refresh.** A split or a §0 restore changes SKILL.md after §2 scored it. Unless skill-check is unavailable or `{skill_check_flag_fallback}` is true, run `npx skill-check check <staging-skill-dir> --format json {security_scan_flag} > "{run_dir}/skill-check.json"` once §4 is done, split or not; after a split, this call is the re-validation above. stdout can go on after the JSON (a `Wrote <path>` line when the project config sets a report path), so read only the JSON object at the start of `{run_dir}/skill-check.json`. If its quality score differs from section 2's, update the evidence-report with the newer score. When the file does not start with a JSON object (exit 2 on a config, option or plugin error, or a stopped call), keep section 2's score.
### 5. Security Scan
Run the scan whether or not skill-check is available. Resolve `{securityScanHelper}` ← first existing path in `{securityScanProbeOrder}` and run it on the staged skill, with the longest timeout your shell tool takes (it ends within two minutes):
```bash
uv run {securityScanHelper} run --package "<staging-skill-dir>"
```
The helper runs [Snyk Agent Scan](https://docs.snyk.io/), which checks a skill for prompt injection and other risks, at the version it pins, only when `SNYK_TOKEN` is set, and reads the scanner's own JSON report, so rely on the JSON it prints, never on an exit code. Bind `{security_result}` ← its `security_result` (`pass`, `warn` or `skipped`) and `{security_note}` ← its `note`, and record each `findings[]` entry's `text` under the evidence report's Remaining Warnings as an advisory warning: security findings do not block artifact generation. For `skipped`, log "security scan skipped: {security_note}" there. When no `{securityScanProbeOrder}` path exists, bind `{security_result}` ← `skipped` and `{security_note}` ← `skf-security-scan.py missing`; when the call prints no JSON object, bind `skipped` and `skf-security-scan.py printed no result`. Log either one as a skipped scan.
**Security row.** §8 writes the `- Security:` row as `{security_result}`, then `{security_note}` in parentheses, such as `skipped (SNYK_TOKEN not configured)` or `pass (the scanner reported no risk)`, with each finding after the note for `warn`. Step 8 takes the row's first word as `security_result`.
**If `{security_note}` is `SNYK_TOKEN not configured`:**
Display: "Security scan requires a Snyk Enterprise API token ([docs](https://docs.snyk.io/snyk-api/authentication-for-api)). Set `SNYK_TOKEN=your-token` in the environment SKF runs in, then run Create Skill again: the scan reads it on every run. Security scanning is optional and does not block skill compilation."
### 6. Description Angle-Bracket Check
The Claude platform does not accept a skill whose frontmatter `description` contains XML tags, and none of the validators this step runs checks for them: skill-check has no such rule and Tessl Review accepts them. Step 5 §2a replaces every `<` with `{` and every `>` with `}` before SKILL.md is written, and the §0 guard puts that description back whenever a tool rewrites it; this section checks the staged result after every tool in this step has run, whether or not skill-check was available.
Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If neither path resolves, or the command below prints no JSON object, **HARD HALT** (exit code 3, `helper-missing`, phase `validate`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Cannot check the staged description: skf-validate-frontmatter.py is missing or did not run. Re-install SKF, then re-run create-skill." Run:
```bash
uv run {frontmatterValidator} "<staging-skill-dir>/SKILL.md" --forbid-angle-brackets
```
Rely on the parsed JSON, not the exit code: the validator also exits 1 for the frontmatter issues §2 and §3 already recorded. Bind `{description_angle_brackets}` ← `description_angle_brackets`.
- **`{description_angle_brackets}` is `0`:** record `Description angle brackets: none` and continue to §6b.
- **`{description_angle_brackets}` is null** (the description is missing, blank or not a string, which §2 or §3 already recorded): record `Description angle brackets: not checked — no description` and continue to §6b.
- **`{description_angle_brackets}` is above `0`:** apply step 5 §2a's substitution again, in place. The guard helper rewrites only the `description` field and takes no description on the command line, so backticks and `$` in it are safe:
```bash
uv run {descriptionGuardHelper} sanitize "<staging-skill-dir>/SKILL.md"
```
Bind `{angle_bracket_substitutions}` ← `substitutions`, `{angle_brackets_sanitized}` ← `sanitized` and `{sanitized_description}` ← `description`. Then run the validator command above once more and bind `{description_angle_brackets}` ← `description_angle_brackets` again.
- **Recovered** (the guard helper exited 0, `{angle_brackets_sanitized}` is true and `{description_angle_brackets}` is now `0`): record `Description angle brackets: re-sanitized ({angle_bracket_substitutions} substitutions)` and continue to §6b.
- **Otherwise** **HARD HALT** (exit code 5, `description-angle-brackets`, phase `validate`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Description sanitization failed: the staged SKILL.md description still holds angle brackets after step 5 §2a's substitution was applied again. The Claude platform does not accept XML tags in a skill description. Check that `<staging-skill-dir>/SKILL.md` can be written, then re-run create-skill." Nothing has been promoted yet, so the halt writes no result file.
### 6b. Tessl Review (optional)
Tessl Review (`tessl review run`, which the helper below runs on a copy of `<staging-skill-dir>`) scores the skill on Tessl's servers with validation checks and two AI judges, one for the description and one for the content. It runs only when the user opted in by setting `tessl_review_workspace` in `{preferencesFile}` to a Tessl workspace name, because it needs a Tessl account, uploads the skill's files to that workspace's review history and spends Tessl credits. The helper applies that setting and every other condition, so run it on every pass and let it decide; `{tesslReviewRules}` explains what is uploaded and what each result means. Nothing in this section halts, asks the user anything, changes the staged files or adds an auto-decision, in interactive and headless runs alike.
Resolve `{tesslReviewHelper}` ← first existing path in `{tesslReviewProbeOrder}`. If neither path exists, set `{tessl_summary}` to `not run — skf-tessl-review.py is missing` and `{tessl_warnings}` to the one line `Tessl Review: {tessl_summary}`, add that line to the evidence report's Remaining Warnings and continue to §7. Otherwise submit the review:
```bash
uv run {tesslReviewHelper} submit "<staging-skill-dir>" --preferences "{preferencesFile}"
```
A review takes Tessl about two minutes, so no call waits for all of it. When the review is on, `submit` sends a copy of the skill to Tessl and returns `pending` with Tessl's run id as soon as Tessl accepts it; when it is off or cannot run, `submit` returns that result instead. While `{tessl_status}` is `pending`, collect the review, at most six times, and add `--final` to the sixth call, which turns a review still running into `timeout`:
```bash
uv run {tesslReviewHelper} collect "{tessl_run_id}" --workspace "{tessl_workspace}" --tessl-version "{tessl_version}"
```
Each call ends within two minutes (a `collect` checks the review for up to 90 seconds, then returns `pending` again or the result), so run each one with your shell tool's default time limit. If the shell tool stops a call before it prints its JSON, or it prints none, make that the last call: set `{tessl_status}` to `failed`, `{tessl_summary}` to `failed — stopped before skf-tessl-review.py reported a result` and `{tessl_warnings}` to the one line `Tessl Review: {tessl_summary}`, keep `{tessl_run_id}` and the other values the calls before it bound, add that line to the Remaining Warnings and continue to §7. Otherwise rely on the JSON, not the exit code, and bind these from the `submit` JSON and again from each `collect` JSON, whose values replace the earlier ones:
- `{tessl_status}` ← `status`
- `{tessl_summary}` ← `summary`
- `{tessl_warnings}` ← `warnings`
- `{tessl_workspace}` ← `workspace`
- `{tessl_version}` ← `tessl_version`
- `{tessl_run_id}` ← `run_id`
- `{tessl_review_score}` ← `review_score`
- `{tessl_description_score}` ← `description_score`
- `{tessl_content_score}` ← `content_score`
- `{tessl_validation}` ← `validation`
- `{tessl_description_suggestions}` ← `description_suggestions`
- `{tessl_content_suggestions}` ← `content_suggestions`
Every key is always present: the scores and `{tessl_validation}` are null and the suggestion lists are empty unless `{tessl_status}` is `reviewed`, and `{tessl_run_id}` is null until Tessl has accepted the review. After the last call, add each entry of `{tessl_warnings}` to the evidence report's Remaining Warnings: a score below 60%, validation errors or, for any status other than `reviewed` and `off`, why the review produced no score. When `{tessl_status}` is `reviewed`, resolve `{tesslReviewRules}` ← first existing path in `{tesslReviewRulesProbeOrder}`, load it, and mark each entry of `{tessl_content_suggestions}` that one of its rules matches with `(not applicable: <rule-id>)`; if neither path exists, list the suggestions unmarked. Apply no suggestion: content suggestions would add text SKF cannot cite to source, and the description comes from the brief. The staged skill holds no `scripts/` or `assets/` until step 7 copies them, so for a brief with scripts or assets, validation findings about missing `scripts/` or `assets/` paths are expected here; test-skill reviews the finished package. §8 records the result.
### 7. Validate metadata.json
**Re-derive the computed fields with `{renderMetadataStatsHelper}` in check mode** rather than re-doing the arithmetic by hand. Resolve `{renderMetadataStatsHelper}` from `{renderMetadataStatsProbeOrder}` (first existing path wins; if neither resolves, **HARD HALT** (exit code 3, `helper-missing`, phase `validate`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Cannot check metadata.json: skf-render-metadata-stats.py is missing. Re-install SKF, then re-run create-skill."), then run it against the staged provenance-map and metadata.json:
```bash
uv run {renderMetadataStatsHelper} <staging-skill-dir>/provenance-map.json \
--check <staging-skill-dir>/metadata.json
```
The helper re-bins `entries[]` by `signature_source`, recomputes `exports_documented`, `exports_total`, and `public_api_coverage` / `total_coverage` (null when the denominator is 0), and cross-checks `stats.scripts_count` / `stats.assets_count` against the `scripts[]` / `assets[]` array lengths and the provenance-map `file_entries` counts. It also checks that each T1 or T1-low provenance entry's `confidence`, `signature_source` and `ast_node_type` match its `extraction_method`, and that no entry read by eye (`source-read`) carries `signature_source: "T1"` at any confidence. It takes the judgment values (`exports_public_api`, `exports_internal`, `effective_denominator`) from `metadata.json` itself and infers the shape from `scope_type` / `skill_type` (pass `--shape` to override). Parse the emitted JSON (rely on the JSON, not the exit code):
- **`coherence.ok: true`** — the computed fields are internally consistent; record "Metadata: PASS".
- **A `provenance.entries[<i>].*` violation** (handle these before any other): entry `<i>` of the staged provenance map (its `export_name` is in the violation) carries a label its `extraction_method` does not allow (one compile §4 did not settle): relabel it by the Relabel Rule in `{relabelRuleData}`, resolving `{verifyProvenanceCompletenessHelper}` ← first existing path in `{verifyProvenanceCompletenessProbeOrder}` for its `kind-at` lookup. Write the relabeled map with `python3 {atomicWriteHelper} write --target <staging-skill-dir>/provenance-map.json`, then re-run the check above and act on its new result: a relabeled `signature_source` moves the distribution, so the computed-value fixes below come from the re-run, and a violation left as a WARN does not block them. Record the relabeled export names, and each WARN left, on the evidence report's `Provenance labels` line (§8).
- **`coherence.ok: false`**: each `violations[]` entry is `{field, expected, actual}` where `expected` is the correct value. **Auto-fix each computed-value violation** (`field` starting `stats.` or `confidence_distribution.`) by setting that field in `metadata.json` to `expected` (write via `python3 {atomicWriteHelper} write --target <staging-skill-dir>/metadata.json`), leaving every other stats field (e.g. `stats.notes` on a reference app) untouched. Record "Metadata: auto-fixed {N} computed-value discrepanc(y|ies)" listing the fields. These are computed values, so the helper is authoritative: a `confidence_distribution` violation is the per-entry mis-binning compile.md §4 describes (T2 annotations + T3 doc items counted on top of the per-export tiers); the helper's per-entry counts replace them. The carve-out is handled by `--shape`: a **reference-app** distribution sums to the per-citation count, a consistent state, not a violation. A `provenance.file_entries.*` violation is not a computed metadata field: it means the provenance-map `file_entries` and metadata counts disagree; record it as a warning for manual reconciliation rather than auto-editing the count.
Then verify the two fields the helper does not own (genuine constants/contract):
- `spec_version` is `"1.3"`.
- `scope_type` is present and equals the brief's `scope.type` verbatim.
### 7a. Verify Provenance Lines and Citation Prefixes
Check that each staged provenance entry's `source_line` is the line that defines its export (the `def` or declaration line itself, not a decorator or blank line above it), and that each `[AST:]` / `[SRC:]` citation in SKILL.md and `references/` carries the prefix its entry's `extraction_method` implies: `ast-grep` gives `[AST:]`, `source-read` gives `[SRC:]`. Also check that each ast-grep entry's `ast_node_type` is a node kind ast-grep knows for its file's language. Resolve `{verifyProvenanceCompletenessHelper}` ← first existing path in `{verifyProvenanceCompletenessProbeOrder}`. If neither path exists, record `Provenance lines: not run: verifier missing` and continue to §8. Otherwise bind `{verify_json}` ← `{project-root}/_bmad-output/.skf-stage/{skill-name}.verify.json` (beside the staging folder, never inside the skill) and, from `{project-root}`, remove the JSON an earlier run left there and run the verifier against the staged package:
```bash
rm -f "{verify_json}"
uv run {verifyProvenanceCompletenessHelper} verify \
--metadata <staging-skill-dir>/metadata.json \
--provenance <staging-skill-dir>/provenance-map.json \
--source-root {source_root} \
--skill-dir <staging-skill-dir> \
--check-node-kinds \
-o "{verify_json}"
```
`{source_root}` is the local tree step 3 extracted from. When it is null, empty or a URL, leave out the `--source-root` line (an empty flag value fails the helper's arguments). When there is no local tree (no flag), the helper checks no source line and reports `summary.stale_check: skipped-no-source-root`, and the citation check still runs. A JSON at `{verify_json}` after the call is this run's: read it, not the exit code (exit 1 means findings). When no JSON is there after the call (an input error, exit 2, `uv` failing, or a shell timeout that stopped it), record `Provenance lines: not run: verifier error`, add the helper's stderr to the evidence report's Remaining Warnings and continue to §8. When `summary.skill_citations_scanned` is above 0 and `summary.skill_citations_matched` is 0, no citation names a path and line the map records (the citations use another root), so the prefix check compared nothing: list that as a WARN. `--check-node-kinds` reports in `node_kinds[]` each `ast-grep` entry whose `ast_node_type` is `ERROR` or not shaped like a kind (judged without ast-grep), or that the ast-grep CLI does not know as a kind of its file's language; each item gives the entry's `entry_index`, `export_name`, `source_file`, `source_line` and `language`. `summary.node_kind_check` is `skipped-no-ast-grep` when no ast-grep CLI is on PATH, or `skipped-unrecognized-ast-grep` when the ast-grep found does not reject a kind no grammar has, so its answers cannot be read: either way ast-grep judged no kind. `node_kinds_unchecked[]` lists, with a `reason`, the entries whose kind ast-grep could not judge, and `summary.node_kind_check_skipped` counts the ast-grep entries in files ast-grep has no language for. Record both on the `Provenance lines` line.
Fix the findings that have one answer, in this order, then run the command above once more:
1. **Citation prefixes and source lines.** Never apply them by hand: from `{project-root}`, run the verifier's `fix` on the JSON the run above wrote:
```bash
uv run {verifyProvenanceCompletenessHelper} fix \
--verify "{verify_json}" \
--provenance <staging-skill-dir>/provenance-map.json \
--skill-dir <staging-skill-dir>
```
It gives each mismatched citation its `expected_prefix`, moves each `source_line` that has exactly one value in `definition_lines` there, with the citations of the old line in SKILL.md and `references/` (a range by both ends, each citation at most once), writes each changed file through the atomic writer, and prints `applied[]`, `left_as_warn[]` (each finding it left, with its `why`), `files_written[]` and `summary`, on exit 0 and on exit 1 (it left a WARN) alike. A `stale[]` item that carries `folded_to` is a bookkeeping variant (`X_def`, `X_exact`, `a11y_X`) its file never names: its line was checked against that base, so its `definition_lines` are the base's. Exit 2 prints no JSON (its stderr line names any file it already wrote): list a WARN, `not fixed: verifier error` with that line, and go on to item 2.
2. **Node kinds.** For each `node_kinds[]` item (`reason` is `invalid-kind` or `error-kind`), take the entry at its `entry_index` in the staged provenance map (its `export_name` and `source_file` confirm it; item 1's `fix` may have moved its `source_line`) and set its `ast_node_type` to the node kind the Relabel Rule in `{relabelRuleData}` gives: the kind of the recipe the export's `ast_recipe` names in the extraction inventory step 3 §5 wrote, `{project-root}/_bmad-output/.skf-stage/{skill-name}.inventory.json`, else its `kind-at` lookup at the entry's current `source_line`. When the rule gives no kind, list a WARN with its reason. Never invent a kind, and never change `extraction_method` to clear the finding. Write the map with `python3 {atomicWriteHelper} write --target <staging-skill-dir>/provenance-map.json`.
If that second run leaves no JSON at `{verify_json}`, record the fixes already applied and `second run: verifier error`, and continue to §8. Fix nothing else, and triage what is left:
- A `left_as_warn[]` item whose `why` is `no-definition-line` is unverified, not gone: the rules found no definition line, which may be a shape they do not cover. List its export as unverified.
- Every other `left_as_warn[]` item needs a person to decide, so list each as a WARN: several definition lines (`several-definition-lines`), a `file-missing`, `line-out-of-bounds` or `line-invalid` item (`needs-decision`), a citation of a line another entry also records, which may cite that export (`shared-line`), a citation or entry `fix` could not find (`citation-not-found`, `entry-not-found`), and a citation inside a `[MANUAL]` block (`inside-manual-block`).
- The helper's `missing` and `orphaned` exports are not line, citation or node-kind findings: add each to the evidence report's Remaining Warnings.
Record the result on the evidence report's `Provenance lines` line (§8): `pass` when the first run found nothing, `findings` when it found something and this section fixed nothing, or what it fixed (`fix`'s `summary.source_lines_moved` and `summary.citation_prefixes_fixed`, and the node kinds item 2 set); then the unverified exports, a WARN for each `left_as_warn[]` item and each other line, citation or node-kind finding the second run still reports, `source lines not checked: no local source tree` when `stale_check` is `skipped-no-source-root`, `node kinds not checked: no ast-grep CLI` or `node kinds not checked: unrecognized ast-grep` when `node_kind_check` is `skipped-no-ast-grep` or `skipped-unrecognized-ast-grep`, each `node_kinds_unchecked[]` entry with its `reason`, and `summary.node_kind_check_skipped` when it is above 0. This section never halts.
### 8. Update Evidence Report
Write the validation results into the staged `<staging-skill-dir>/evidence-report.md`, in place of the `[PENDING: populated by step 6]` placeholders compile left and of the line under `## Auto-Fixed Issues`, which compile wrote before §2 ran, with `python3 {atomicWriteHelper} write --target <staging-skill-dir>/evidence-report.md`: step 7 promotes that file as it is. In the same write, add under `## Remaining Warnings` the notes steps 5a to 5c kept for the evidence report (the doc-sources note, `{temporal_feeder_notice}` when step 5c set it, because the Deep-tier temporal feeder held no files) and, once each, the skipped authoritative-files scan when the inventory's `authoritative_files_scan` records `not_scanned` (a remote source that was never cloned; the `skipped` count of candidates the user skipped is not a warning). When no split ran and the staged `references/` holds no file, the Body line says `Tier-2 kept inline (references/ empty)`, so an audit can tell inline by design from a split that failed.
```markdown
## Validation Results
- Schema: {pass/fail} (quality score: {score}/100)
- Frontmatter: {pass/fail}
- Body: {pass/fail} {body split applied if applicable}
- Security: {pass/warn/skipped} ({the note §5's Security row gives})
- Description angle brackets: {none | re-sanitized ({count} substitutions) | not checked — no description}
- Tessl Review: {tessl_summary}
- Metadata: {pass/fail}
- Provenance labels: {pass | relabeled {N} to match extraction_method: {export names}}{; WARN, no node kind found: {export names}}
- Provenance lines: {pass | findings | fixed {N} source lines, {M} citation prefixes and {K} node kinds | not run: verifier missing | not run: verifier error}{; second run: verifier error}{; unverified, no definition line found: {export names}}{; WARN: {each line, citation or node-kind warning §7a lists}}{; source lines not checked: no local source tree}{; node kinds not checked: no ast-grep CLI | unrecognized ast-grep}{; node kinds unchecked: {export name (reason) for each node_kinds_unchecked item}}{; node kinds skipped: {N} in files ast-grep has no language for}
## Quality Score Breakdown
- Frontmatter (30%): {score} | Description (30%): {score} | Body (20%): {score} | Links (10%): {score} | File (10%): {score}
## Description Guard
- Restored: {true/false}
- Triggering tool: {tool_name or —}
- Original description preserved: {true/false}
- Notes: {one-sentence detail or —}
## Auto-Fixed Issues
- {"skill-check --fix rewrote SKILL.md" when §2 recorded `skill_check_fix_changed: true`, "SKILL.md may have been rewritten (not hashed) by skill-check --fix" when it recorded `skill_check_fix_changed: unchecked`, otherwise "none"}
## Remaining Warnings
- {warnings and security results, then each entry of {tessl_warnings} — or "none"}
## Tessl Review
- Result: {tessl_summary}
- Workspace: {tessl_workspace or —} · tessl {tessl_version or —} · Run: {tessl_run_id or —}
- Validation findings: {each {tessl_validation} finding as `name (status): message`, or "none"}
- Description suggestions (to act on one, edit the description in the brief and re-run create-skill): {each of {tessl_description_suggestions}, or "none"}
- Content suggestions (advisory, not applied): {each of {tessl_content_suggestions} with its `(not applicable: <rule-id>)` mark, or "none"}
```
When `{tessl_status}` is not `reviewed`, the `## Tessl Review` section holds only its Result line and, when `{tessl_run_id}` is set, its Workspace line, so the report names the run of a review that may still finish.
**Auto-Decisions:** keep the `## Auto-Decisions` section step 5 §7 rendered from the run sink as it is: every gate decided before step 5, and no step records a decision after it, so its rows already match `summary.auto_decision_count`.
**Description Guard population:** if the §0 protocol fired during §2 (`skill-check --fix`) or §4 (the body split), fill the four Description Guard fields from context:
- `Restored: true` when `description_guard_restored == true`, otherwise `false`.
- `Triggering tool`: the tool name recorded by §0 (`skill-check --fix` in §2, `skf-shard-body.py` in §4), or the template's no-fire dash if the guard did not fire.
- `Original description preserved`: `true` if the restore succeeded (on-disk now matches the pre-tool snapshot), `false` if restoration itself failed (rare — treat as a halt condition in a future version).
- `Notes`: a one-sentence description of what the tool had changed, based on the recorded `description_guard_diff_kind` (`replaced`, `truncated` or `deleted`). Typical values: `"replaced with generic summary"`, `"truncated at N chars"`, `"angle-bracket tokens re-introduced"`, `"field deleted entirely"`. If `Restored: false`, use `—`.
When `Restored: false`, the three follow-up fields are all `—` — this is the clean-run expected state — with one exception: when `description_guard_refused == "empty-capture"` (§0's empty-snapshot rule — `verify-restore` exited 1 and no in-context copy allowed a re-run), the guard did fire and must not render as a clean run. Set `Restored: false`, `Triggering tool` to the recorded tool name, `Original description preserved: false`, and `Notes: guard refused — empty captured snapshot (empty-capture)`.
### 9. Auto-Proceed
No user interaction: this step has no gate. After validation completes, load `{nextStepFile}`, read it fully, then execute it. Tool unavailability, validation failures and every Tessl Review result are recorded as skips and warnings; the step halts only where a section above says HALT: a helper whose probe order says HALT and that no path resolves, the §4 Tier-1 preservation and cross-reference checks, and the §6 description check.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |