# Skill Builder > Reviews and improves SKILL.md packages by fixing audit findings, triggers, examples, evals, token budget, release proof, safety verdicts, comparator/baseline choices, and bounded code-lens hardening. Use when the user says improve a skill, fix a skill file, review SKILL.md, raise Tessl score, reduce context cost, add skill evals, or prepare a plugin skill for release. - Skill: `jscraik/skill-builder` (Agent Skill, multi-file: 27 files) - Install (CLI): `npx skillmds@latest add jscraik/skill-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/jscraik/skill-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: jscraik (https://skillmd.com/u/jscraik) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/jscraik/skill-builder --- # 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. - If the target, failing gate, score, or edit authority is missing, ask Round 1 question: Which canonical target should I patch? If canonical and .agents/** paths both exist, confirm the source before edits. ## Outputs - Exact validation commands and pass, fail, or blocked outcomes. - Changed files, rollback path, and evidence artifact locations. - 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. Find the canonical source and confirm edits are allowed. 2. Read references/repair-policy.md for first-principles gate, repair map, Tessl policy, and scenario policy. 3. For review, handoff, rollback, or validation-only work, return the Outputs contract and stop. 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 Pass only on parsed fields: ask audit, package, and release status == success; external-review lint ok plus score >= 90 with 95+ target; Tessl live-private usage >= max(0.90, baseline) only when the workspace/project link is available. On failure, patch the first errors[] item or blocker. Exit code alone never passes. ## 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 - 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.