| name | skill-builder |
| description | 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. |
| metadata | {"version":"1.0.0","skill-type":"code_quality_review","lifecycle_state":"active","maturity":"canonical","owner":"Agent Skills Team","provenance":"frontmatter:Agent Skills Team:2026-05-15:canonical-source","share_readiness":"ready","review_cadence":"quarterly","last_reviewed":"2026-05-15","metadata_source":"frontmatter","compatible_roles":["default","worker","skill-inspector"],"runtime_needs":["repo-owned skill source path","./bin/ask skills audit and eval wrappers","python3 standard library validators"]} |
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
- Find the canonical source and confirm edits are allowed.
- Read references/repair-policy.md for first-principles gate, repair map,
Tessl policy, and scenario policy.
- For review, handoff, rollback, or validation-only work, return the Outputs
contract and stop.
- Run the focused gate; record baseline score, artifact path, and first
blocker.
- Apply one Repair Map change from references/repair-policy.md, then rerun the
same gate.
- If score or blocker is flat, undo or narrow and try the next map item. After
three flat loops, stop with blocker_notes.
- 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.
