CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

optimize-skill-instructions

Review and improve your skill with actionable recommendations. Reviews the whole bundle, validates syntax and references, explains rubric, shows before/after scores, and edits the SKILL.md and its reference docs. Use when reviewing skill quality, improving a SKILL.md or its reference files, checking scoring dimensions and quick wins, auditing progressive disclosure and orphaned bundle files, generating improvement recommendations, running a post-edit quality audit, creating approval-gated change proposals, or automating the skill review workflow. For the full optimization cycle (review + evals + improve), use `optimize-skill-performance-and-instructions`.

1.14x
Quality

92%

Does it follow best practices?

Impact

89%

1.14x

Average score across 29 eval scenarios

SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is tessl/skill-optimizer

SKILL.md
Quality
Evals
Security

Quality

Content

92%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An exemplary workflow skill body: fully executable commands and templates, an eight-phase sequence with validation before edits and an approval gate, a re-review/verify loop, and a well-signaled one-level-deep reference with no orphaned files. The only trimmable fat is the redundant closing Notes section.

DimensionReasoningScore

Conciseness

The body is dense and instructive — every phase carries directive content with no concept explanations Claude already knows. Minor trims exist: the closing "Notes" section restates points already made in the phases ("Validates syntax/commands before applying", "Uses `tessl review run` for evaluation"), and Phase 8's checklist reiterates Phase 4's items. This fits anchor 4 ("efficient; minor instances of over-explanation that could be trimmed") better than anchor 3, since the repetition is small and the Phase 8 re-check is an intentional verification loop.

4 / 5

Actionability

Fully executable throughout: exact commands with flags (`tessl review run <path-to-skill> --label "baseline"`, `--threshold`, `tessl review fix ... --max-iterations 3 --threshold 85`, `--yes`, `--review-plugin`), a copy-paste-ready orphan-detection bash snippet, an exact recommendation-block template, and a concrete priority-table format — matching the anchor-5 'copy-paste ready commands covering common cases'.

5 / 5

Workflow Clarity

Eight clearly sequenced phases with explicit validation checkpoints and feedback loops: Phase 4 mandates validating syntax/flags/references **before** applying, Phase 6 is approval-gated with minimal conservative edits, Phase 7 re-runs the review and shows before/after score comparison, and Phase 8 re-validates and fixes any issues. This matches the anchor-5 pattern (validate → fix → re-validate, with checklists) that the rubric reserves for batch/edit operations.

5 / 5

Progressive Disclosure

Scored against the actual bundle (SKILL.md + references/REFERENCE.md, which exists): the one reference file is linked exactly once with a strong what/when signal — "See [REFERENCE.md](references/REFERENCE.md) for validation code snippets (Python `ast.parse`, JS `node --check`, bash file-reference checks)" — matching the rubric's ✅ example. It is one level deep, there are no orphaned bundle files, the body teaches orphan/link hygiene itself, and section headers (Workflow phases, Fast path, Customizing, Progressive Disclosure) make navigation easy — matching anchor 5.

5 / 5

Total

19

/

20

Passed

Description

91%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: concrete capability list, an explicit multi-phrase "Use when..." trigger clause, and proactive disambiguation from sibling skills. The only deductions are the second-person "your skill" phrasing (specificity penalty per rubric guideline) and minor overlap risk with the closely related optimization/review-plugin skills.

DimensionReasoningScore

Specificity

Lists multiple concrete actions — "Reviews the whole bundle, validates syntax and references, explains rubric, shows before/after scores, and edits the SKILL.md and its reference docs" — which matches the anchor-5 example in coverage. However, the opening "Review and improve your skill" uses second-person possessive ("your"), and the rubric guideline penalizes second-person voice by reducing specificity by 1, so it drops to 4 rather than the anchor-5 'Processes files'-style third person.

4 / 5

Completeness

Explicitly answers both questions: what it does (the five concrete capabilities) and when to use it (a full "Use when reviewing skill quality, improving a SKILL.md..." clause with concrete triggers), structurally identical to the anchor-5 example. It also adds a routing sentence to the sibling skill for the full cycle.

5 / 5

Trigger Term Quality

The "Use when..." clause enumerates eight natural trigger phrasings users would actually say: "reviewing skill quality", "improving a SKILL.md or its reference files", "checking scoring dimensions and quick wins", "auditing progressive disclosure and orphaned bundle files", "generating improvement recommendations", "running a post-edit quality audit", "creating approval-gated change proposals", "automating the skill review workflow" — comprehensive synonym coverage matching the anchor-5 example.

5 / 5

Distinctiveness Conflict Risk

Clear niche (skill-quality review via `tessl review`) with distinct triggers, and the explicit handoff to `optimize-skill-performance-and-instructions` and `create-review-plugin` reduces routing confusion. But triggers like "improving a SKILL.md" and "automating the skill review workflow" carry minor overlap risk with those closely related sibling skills, which fits anchor 4 ("mostly distinct; minor overlap risk with closely related skills") better than anchor 5's "minimal conflict risk".

4 / 5

Total

18

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

tesslio/product-plugins

Path

skill-optimizer/skills/optimize-skill-instructions/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.