CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

formal-review

This skill should be used when the user asks to "formal review", "formal lens review", or invokes /formal-review. A fixed-lens PR review for this repository's formally-structured protocol changes: it pins a Category Theory / Type Theory / Operational Semantics lens panel over only the files changed in a PR, analyzes each lens in isolation, adversarially cross-verifies the findings, and posts the survivors as a single consolidated PR comment. Project-local contributor tooling.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

73%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.

The body presents a clearly sequenced, well-validated five-phase workflow with genuinely concrete commands and thoughtful edge-case handling, so a competent executor knows exactly what to do. Its weaknesses are token efficiency — the core invariants are repeated many times and some meta-justification prose could be cut — and a posting step described in prose where a copy-paste command would be tighter. Instruction-only guidance is otherwise actionable enough that the absence of code blocks is not penalized.

Suggestions

State the fixed-lens panel invariant once (e.g. in the Pipeline Overview) and reference it elsewhere instead of restating it in the intro, 'Why this is a project skill', Caller Signature, When to Use, Phase 2, and Rules — this alone would cut meaningful tokens.

Replace the prose description of the JSON body construction with the actual copy-paste command, e.g. jq -n --rawfile body comment.md '{"body": $body}' | gh api repos/{owner}/{repo}/issues/{N}/comments --input -.

Delete execution-irrelevant meta-commentary (the /conduct activation-precondition justification, the repeated 'the diff headers are authoritative' restatements) and the basic diff-reading conventions explaining +/- lines, which Claude already knows.

DimensionReasoningScore

Conciseness

The instruction content is real and dense, but the fixed-panel invariant is restated roughly seven times across sections, the "/conduct activation precondition" justification is execution-irrelevant meta-commentary, and "Diff-reading conventions: lines starting with + are added" explains what Claude already knows — mostly efficient but could be tightened considerably, anchor 3 rather than 2 since padding is redundancy rather than concept explanation.

3 / 5

Actionability

Concrete executable commands appear throughout (gh pr view --json number, git status --porcelain, gh pr diff {N}, gh api repos/{owner}/{repo}/issues/{N}/comments) with precise shell-safety posting discipline, but the jq --rawfile JSON-body construction step is described in prose rather than given as a copy-paste command — mostly executable with minor gaps, anchor 4.

4 / 5

Workflow Clarity

Five explicitly sequenced phases with real validation checkpoints: adversarial refutation with survival criteria (Phase 2b), the ≥80% confidence threshold, the Phase 3 direction-error guard, the untracked-file edge case, the trivial-change skip, and harness permission gating of the external write, plus a Rules checklist — matches the anchor-5 pattern of explicit validation with error-recovery handling.

5 / 5

Progressive Disclosure

Well-organized single-file structure with clear section headers and no nested references, self-contained by design with no bundle files to navigate; however, at ~125 lines everything is inlined (beyond the under-50-line simple-skill exception), so this is good placement with minor organization gaps (anchor 4) rather than the ideal split of anchor 5.

4 / 5

Total

16

/

20

Passed

Description

92%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.

The description is specific, complete, and distinctive: it names the exact lens panel, the full action chain from diff to posted comment, and explicit trigger phrases including the slash command. The only weakness is that trigger coverage omits a few natural synonyms a user might plausibly say. Third person voice is used throughout, so no voice penalty applies.

DimensionReasoningScore

Specificity

Lists multiple concrete actions covering the full pipeline — "pins a Category Theory / Type Theory / Operational Semantics lens panel over only the files changed in a PR, analyzes each lens in isolation, adversarially cross-verifies the findings, and posts the survivors as a single consolidated PR comment" — comprehensive with no coverage gaps, matching the 5 anchor rather than 4.

5 / 5

Completeness

Explicitly answers both questions: what ("a fixed-lens PR review... pins... analyzes... cross-verifies... posts") and when with concrete trigger phrases ("should be used when the user asks to 'formal review', 'formal lens review', or invokes /formal-review"), matching the anchor-5 example pattern.

5 / 5

Trigger Term Quality

Triggers "formal review", "formal lens review", and "/formal-review" are natural user phrasings plus the slash command, but a few plausible variations (e.g. "formal lenses", "category-theory review") are absent — good coverage with minor gaps, anchor 4 rather than comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

Clear niche — formal-lens PR review of "this repository's formally-structured protocol changes" — with distinct triggers and explicit "Project-local contributor tooling" scoping, giving minimal conflict risk with generic review skills.

5 / 5

Total

19

/

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

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

Total

15

/

16

Passed

Repository

jongwony/epistemic-protocols

Path

.claude/skills/formal-review/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.