Optimize Skill Instructions

Review Best Practices

Improve your skill using tessl review run plus validation and context: it reviews your full skill bundle, validates syntax, explains WHY changes help, and catches mistakes before applying.

For a hands-off, automated improve loop, use tessl review fix instead — see Fast path: automated fix loop.

Guiding Principles

• A judge suggestion that conflicts with the skill's purpose should be discussed as a trade-off, not silently applied
• Don't invent rubric dimensions, score deltas, or tessl review flags — derive them from actual review output

Workflow

Phase 1: Baseline Evaluation

tessl review run <path-to-skill> --label "baseline"

Pass --threshold <percent> to exit non-zero below a score gate. Re-open the most recent result with tessl review view --last.

Parse output for scores, validation issues, and judge suggestions. Prioritize fixes: Critical (ERRORs) → High (missing "Use when...", low actionability/conciseness) → Medium (other dimensions) → Low (warnings)

Phase 2: Discover Skill Bundle

Read SKILL.md and list files in its directory. Bundle = SKILL.md + sibling files + referenced files. Check for orphaned files (see Progressive Disclosure section). Use bundle context to improve progressive disclosure.

Phase 3: Generate Recommendations

For each issue, produce a recommendation block:

## [Action verb]: [what to change]

Dimension: [name] [current]/3 → [target]/3 (+Z% overall)

Before:
> [exact current text]

After:
> [exact replacement text]

Why: [one sentence: how this improves routing/clarity/actionability]

If bundle has reference files, recommend linking instead of inlining for progressive disclosure.

Phase 4: Validate Recommendations

CRITICAL: Validate before applying changes

Run each validation step and show the output — do not just describe what you would run:

• Python: run ast.parse on any Python code blocks and show the output (including any SyntaxError details)
• JavaScript: run node --check <file> and show the result
• Commands: consult --help output to verify flags are valid
• Files: check that every referenced file path exists
• Frontmatter description: field: verify it contains a "Use when..." trigger clause (check the YAML header, not the body)
• Content: flag any concepts the agent already knows (explain nothing obvious)

See REFERENCE.md for validation code snippets (Python ast.parse, JS node --check, bash file-reference checks). When producing an automation script, include each step as executable code (not comments).

Phase 5: Present Recommendations

Start with a priority summary table before individual details:

Priority | Recommendation           | Score impact | Dimension
---------|--------------------------|-------------|----------
Critical | Add "Use when..." clause  | +15% overall | Completeness 0→3
High     | Remove HMAC explanation  | +8% overall  | Conciseness 1→2
Medium   | Add retry example        | +5% overall  | Actionability 2→3

Then expand each row using the recommendation block format from Phase 3.

The dimension names above are illustrative — use the actual dimensions from your review output. They come from the active reviewer's judges (the default reviewer scores a description and a content judge); a custom reviewer can define different ones.

When a recommendation has a trade-off (e.g. conciseness gain vs. domain context loss), present both options and ask. Frame changes as proposals; get user approval before applying.

Phase 6: Apply Changes

Use the Edit tool to update the SKILL.md and any reference docs the review flagged (e.g. a references/*.md link fix, or moving inlined content out of SKILL.md for progressive disclosure). Keep edits minimal and conservative. For issues in non-prose bundle files (scripts/, assets/), surface them for the user rather than rewriting them here. Track applied recommendations and expected impacts.

Phase 7: Verify Improvement

Run review again:

tessl review run <path-to-skill> --label "verify"

Compare scores:

Before: 72% | After: 89% (+17%)
- Completeness: 2/3 → 3/3 (added "Use when..." clause)
- Actionability: 2/3 → 3/3 (added executable code)
- Conciseness: 1/3 → 2/3 (removed verbose explanations)

Explain which dimensions improved and their impact on the overall score.

Phase 8: Final Accuracy Check

Re-run validation from Phase 4 on the updated SKILL.md:

• ✓ Code syntax valid
• ✓ Command flags correct
• ✓ File references exist
• ✓ Description has "Use when..." clause
• ✓ No concepts Claude already knows

Fix any issues, then re-run tessl review run to confirm improvement.

Fast path: automated fix loop

When the user wants hands-off iteration rather than the approval-gated workflow above, use tessl review fix. It runs the review-and-fix loop automatically — improving the skill and re-reviewing up to --max-iterations (default 3, max 10), stopping early once it hits --threshold:

tessl review fix <path-to-skill> --max-iterations 3 --threshold 85

It downloads the improved bundle, prints the baseline → final score, and asks for confirmation before applying (pass --yes to auto-apply). Note tessl review fix has no --label flag.

Choose between the two paths:

• Manual workflow (Phases 1–8): when you want syntax/command validation, trade-off discussion, and approval-gated control over each change.
• tessl review fix: when you want speed and are comfortable with the reviewer applying changes automatically.

Customizing the reviewer

Both tessl review run and tessl review fix use the default reviewer unless you pass --review-plugin <local-dir | workspace/plugin[@version]>. Most users keep the default. To author a custom reviewer that adds or removes judges and scoring dimensions, use the create-review-plugin skill (tessl/review-plugin-creator).

Progressive Disclosure

Every link must signal WHEN it's relevant:

• ✅ "See [AUTH.md] for OAuth flow setup, token refresh, and session management"
• ❌ "See [GUIDE.md] for more details"

Check for orphaned files:

Files in the bundle that are never referenced add bloat without providing value.

# Find files that exist but aren't linked
ls skill_dir/ | grep -v SKILL.md
grep -oE '\[[^]]*\]\(([^)]+\.md)\)' SKILL.md | cut -d'(' -f2 | cut -d')' -f1
# Compare: files that exist but aren't in the grep output = orphaned

For each orphaned file, recommend:

• ✅ Link it with clear routing signals: "See [FILE.md] for X when Y"
• ❌ Remove it: "FILE.md exists but is never referenced—remove to reduce plugin bloat?"

Don't leave unreferenced files in the bundle. They waste space and confuse maintainers.

Notes

• Modifies the SKILL.md and its reference docs; surfaces (but doesn't rewrite) issues in scripts/assets
• Uses tessl review run for evaluation, or tessl review fix for the automated loop
• Validates syntax/commands before applying
• For bulk/PR work on external repos, iterate this workflow per skill or automate with a script