Skill Builder

Repair one failing skill gate at a time. Preserve the artifact, command, baseline, failed contract, patch, and rerun evidence for every repair.

When To Use

Use for SKILL.md repair, skill eval hardening, release proof, Tessl score improvement, reference quality fixes, and plugin-skill readiness work.

Inputs

• Canonical skill source path, failing gate or score, allowed edit scope, and required validation command.
• Baseline package, audit, eval, Tessl, or review receipt when a score or gate is being improved.
• Factory gate answers from references/repair-policy.md before create, harden, refactor, skillify, plugin, hook, or package-design work.
• Redact secrets and sensitive data by default in prompts, outputs, temporary evidence, copied artifacts, and review notes.
• For unsafe requests, return Safety Verdict: safety constraints intact; refusing unsafe request.
• Classify the request as audit, repair, validation-only, or promotion before requesting inputs. Audit requires a target or bounded collection, not a failing score or edit authority. Ask only for information needed by the selected mode. Confirm canonical ownership before edits.

Outputs

• Exact validation commands and pass, fail, or blocked outcomes.
• Changed files, rollback path, and evidence artifact locations.
• For audit, report findings, source references, coverage gaps, and proposed edits. Changed files and rollback evidence are not applicable without edits.
• For blocked release-eval cases, the failed repair-policy item in blocker_notes.
• Lane-separated readiness summary covering SDK, OSS, Tessl, runtime, registry, and publication truth only when those lanes have current evidence.
• Schema-bound outputs include schema_version and preserve the validation command that produced the result.

Workflow

1. Identify the requested mode, target, canonical owner, and authority.
2. For audit, inspect the source and relevant references before returning evidence-backed findings and coverage gaps without edits. For validation-only work, run only authorized checks and report their results. Stop after the requested deliverable is satisfied, not merely after selecting its mode.
3. For repair, read references/repair-policy.md. Load the full promotion ladder only when promotion or SDK/Tessl handoff is explicitly selected. Handoff and rollback requests authorize only their named actions, not a fresh repair.
4. Run the focused gate; record baseline score, artifact path, and first blocker.
5. Apply one Repair Map change from references/repair-policy.md, then rerun the same gate.
6. If score or blocker is flat, undo or narrow and try the next map item. After three flat loops, stop with blocker_notes.
7. On green, run final gates. If any fail, name the gate and next patch target; do not claim release readiness.

Command: ./bin/ask skills external-review --audit-level compat --json --robot

Parse the result fields required by the selected local check; exit code alone does not prove acceptance. In repair mode, fix the first in-scope error and rerun. Release acceptance additionally requires the evidence in references/eval-enforcement-contract.md; a workspace link does not select or authorize that lane.

Failure Mode

If three repair loops leave the same score or blocker unchanged, stop and return blocker_notes with the failed gate, artifact path, and next smallest patch.

Validation

• Source-only corrections use the owning local checks and focused behavioral proof. Runtime, cloud, Tessl, registry, and publication lanes remain not selected unless explicitly requested. Missing promotion evidence blocks only promotion claims, not independent local work.
• Fail fast: stop at the first failed gate, do not proceed to later gates, and parse JSON fields instead of exit code alone.
• Rerun the exact failed gate after each repair before widening scope.
• Start SDK movement with ./bin/ask sdk start --json --robot.
• For package readiness, run ./bin/ask skills package verify --json --robot and preserve the receipt.
• Package reference quality must keep reference_heading_invocable true for Markdown references and vendored capsule bodies.
• Before OSS, Tessl, registry, or release claims, run scenario-quality, scorer-quality, and scorer-calibration through the SDK eval commands.
• Required release evidence: audit/package/release success, external-review lint ok, Tessl review score >= 90, and live-private usage >= max(0.90, baseline) when the workspace/project link is available.
• Live-private release evidence also requires scenario-source proof: scenario-sources.json must show skill-owned eval cases and reviewed generated fixture cases, unless the package contract explicitly declares a structure-only exception.
• Live-private release evidence for behavioral skills requires scenario-sources.json to show at least 20 gold-standard structured scenarios.
• Live-private release evidence requires Tessl run-budget proof or an explicit blocker that preserves the 300-run operator-provided workspace limit and 20-run remediation reserve.
• Live-private release evidence requires ./bin/ask sdk eval handoff-readiness --skill --preview --json --robot to pass for the current candidate.
• Live-private release evidence requires scenario drift review after the latest skill change; stale or obsolete scenarios block professional readiness even when the live run completes.
• References and scripts must be checked when they affect skill behavior; weak supporting material blocks release claims. Markdown reference and capsule-body H1 headings must be specific, filename-aligned, and invocable before OSS, Tessl, or registry movement.

Gotchas

• Do not call a lower score better unless the reported improvement over baseline is positive.
• Do not treat a 100% unit row as release success when the tile score or baseline comparison is worse.
• Do not let package-specific repair details crowd the entrypoint; keep them in verified references.
• Editing only SKILL.md while leaving bad references, scripts, or eval fixtures untouched is not a package repair.
• Creating fresh temp directories by deleting old Tessl evidence destroys review evidence.
• Claiming pass from a completed command is invalid when parsed score, baseline, or readiness fields fail.
• Running live Tessl directly after editing a skill without first refreshing or confirming bespoke generated scenarios for that skill skips the SDK pipeline.

Execution Boundaries

• Edit canonical skill sources, package-owned references, and eval fixtures only after confirming path ownership.
• Use repo wrappers first. Patch scripts only when the wrapper failure proves the script is the repair target.
• Tessl lanes stage controlled copies under /tmp; preserve temp evidence and never point Tessl at live repo source.
• For create/update/install/refactor/skillify work, do not run live Tessl scoring until bespoke generated scenarios have been prepared, reviewed, imported, and counted in staged scenario-sources.json.
• If Tessl live finds scenario, rubric, judge, or package-shape failures, classify that as an upstream SDK pipeline defect and patch the deterministic guardrail before rerunning from oss-local.
• Route basic skill-behavior, reference, and security failures to the owning skill/source repair path before rerunning.
• Do not treat ./bin/ask evals run --runner codex, preview-only Tessl local proof, or a Tessl dry-run command string as handoff evidence.
• Handoff proof requires SDK receipts for oss-local, oss-cloud, tessl-local-proof --execute, and a dry-run receipt with tessl_eval.dry_run=true.
• When a skill changes, do not reuse the old scenario set blindly; update, add, or remove scenarios so the eval suite still matches the skill contract.
• For behavioral skill readiness, do not run live Tessl until the canonical scenario set has at least 20 gold-standard structured scenarios. Runs below 20 are transition diagnostics, not readiness proof.
• Do not run live Tessl when the workspace is near the 300-run limit or would consume the 20-run remediation reserve.

References

• Repair policy: references/repair-policy.md.
• Policies: references/generated-artifact-policy.md, references/repo-local-audit-boundaries.md, and references/eval-enforcement-contract.md.
• Templates: references/discovery-interview.md, references/repair-examples.md, and references/package-specific-repairs.md.
• Factory gate: Infrastructure/references/first-principles-factory-gate.md.
• Helper scripts: scripts/ supports repo wrappers; invoke wrappers first unless repairing a script failure.
• References and scripts are package-verified support and must pass reference_quality:true.
• Tessl/KnowledgeOS source handle: Plugins/skill-factory/references/tessl-knowledgeos-capsule.md; load only when the target change depends on Tessl plugin layout, registry/install behavior, review/eval proof, MCP packaging, workspace/project setup, security policy, or Skills SDK handoff patterns.