CtrlK
BlogDocsLog inGet started
Tessl Logo

optimize-skill

Use when iteratively optimizing an existing SKILL.md (or a skill folder with bundle files) — runs a Tessl-gated Ralph loop with snapshot-and-revert protection, never accepts a worse `tessl review run` score, and stops when no candidate change improves both the score and the structural quality. Triggers for `/optimize-skill PATH`, "make this skill better", "iterate on this SKILL.md", "improve this skill's tessl score".

72

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

77%Weight 40%Scale 1-3

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

The skill is highly actionable with clear, validated workflow gating, but it is verbose due to restating the loop across flowchart, steps, data-flow, and acceptance-criteria sections, and its only progressive-disclosure reference (REFERENCE.md) does not exist in the bundle.

Suggestions

Collapse the mermaid flowchart, Data flow block, and Acceptance Criteria into the Step Details as a single canonical representation of the loop to remove ~60 lines of cross-redundancy (improves conciseness).

Create the referenced REFERENCE.md (or remove the references to it) so the one-level-deep progressive-disclosure pointer resolves to an extant file, satisfying G4 and lifting progressive_disclosure.

Tighten editorial commentary ('the author has the worst judgment of their own work', restated 'Core rule') to single statements where the gating logic already enforces the same behavior.

DimensionReasoningScore

Conciseness

The body is ~240 lines and restates the same iteration loop four ways — a mermaid flowchart (lines 33-57), Step Details (59-178), the Data flow diagram (204-238), and the Acceptance Criteria / 'What we do NOT want' sections (180-202). It is mostly efficient and free of concepts Claude already knows, but the cross-redundancy means it could be tightened. Not level 3 because the repeated representations of one loop are unnecessary tokens; not level 1 because it is not padded with beginner explanations.

2 / 3

Actionability

Provides fully executable, copy-paste-ready bash: jq filters ('.review.reviewScore // .weightedScore // .score'), rsync snapshot/revert, awk numeric comparison, and the devflow feeder block. Specific flags and env vars are named. Not level 2 because the code is complete and executable rather than pseudocode.

3 / 3

Workflow Clarity

The Iterate step sequences snapshot → apply → score → co-gate → keep/revert with explicit validation checkpoints, and the Acceptance Criteria table (G1-G7) provides a hard-gate checklist with feedback loops (revert on regression, revert entire run if G2 fails). Not level 2 because validation is explicit, not implicit.

3 / 3

Progressive Disclosure

The body offloads detail to a sibling 'REFERENCE.md' with clear one-level-deep signaling ('read REFERENCE.md (sibling)'), but no bundle files exist in references/scripts/assets and REFERENCE.md itself is absent — the reference points nowhere, so the actual bundle structure is empty. Additionally the main file carries the flowchart, step details, and data-flow sections inline where a single canonical representation would suffice. Not level 3 because the signaled reference does not resolve to an extant file; not level 1 because references are one-level-deep and clearly signaled rather than deeply nested.

2 / 3

Total

10

/

12

Passed

Description

100%Weight 40%Scale 1-3

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

The description is specific, trigger-rich, and answers both what and when with explicit, natural-language triggers. It is among the strongest examples and needs no changes.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: 'runs a Tessl-gated Ralph loop with snapshot-and-revert protection, never accepts a worse tessl review run score, and stops when no candidate change improves both the score and the structural quality.' This matches the level-3 anchor and exceeds level-2 (which would only name the domain and some actions).

3 / 3

Completeness

Explicitly answers both 'what' (iteratively optimizing an existing SKILL.md via a Tessl-gated loop) and 'when' (an explicit 'Use when...' clause plus a 'Triggers for...' list). Not level 2 because the 'when' is explicit, not merely implied.

3 / 3

Trigger Term Quality

Provides natural trigger phrases users would say — 'Triggers for /optimize-skill PATH, "make this skill better", "iterate on this SKILL.md", "improve this skill's tessl score"' — giving good coverage, not just technical jargon. It is not level 2 because common user phrasings are explicitly enumerated rather than merely implied.

3 / 3

Distinctiveness Conflict Risk

Has a clear niche — Tessl-gated skill optimization with snapshot-and-revert — and distinct triggers unlikely to fire for unrelated skills. Not level 2 because the combination of Tessl/iteration/score-gating is highly specific, not a broad overlap candidate.

3 / 3

Total

12

/

12

Passed

Validation

100%

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

Validation16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
AndreJorgeLopes/proof-of-skill
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.