CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

state-machines

Finds the implicit state machines in an app: status, state, stage, phase, and step fields, groups of booleans that act like one status, and flows spread across UI, mutations, webhooks, and scheduled jobs. Reports every state, every function that moves it, who can trigger each move, and the problems, then proposes an explicit transition map. Report only by default. Use when the user says find the implicit state machines, audit status fields, map the order or onboarding flow, or when a status bug, a skipped step, or a double run refund, payout, or email shows up.

Quality

97%

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

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

A tightly written, highly actionable audit skill: executable search commands, a concrete report template, a clear stop-before-fixing checkpoint, and proper offloading of detail to a real one-level reference. The only gap is the absence of an explicit post-fix verification loop in the fixing workflow.

Suggestions

In 'Fixing a machine', close the loop explicitly: after step 7, instruct to run the new out-of-order test and re-run the audit step (or re-generate the machine's report entry) to confirm the problem is resolved before moving to the next machine.

Add a brief checkpoint after step 4 of the audit (e.g., verify every writer found in step 3 has an identified trigger) so gaps in actor attribution surface before the report is written.

DimensionReasoningScore

Conciseness

The body is lean and assumes competence: it opens with a skill-specific framing of "implicit state machine" rather than a textbook definition, gives copy-paste rg commands, a compact report template, and terse rules ("Never" list, hand-off table). Nothing explains concepts Claude already knows, matching the 5 anchor where every token earns its place.

5 / 5

Actionability

Guidance is executable throughout: three ready-to-run rg searches with globs, exact Convex entry points (convex/schema.ts, convex/http.ts, convex/crons.ts), a complete report format with a worked example, and numbered fix steps ("Type the field as a union of literals", "Add a test that calls a move out of order and expects it to throw"). The transition-helper code is correctly delegated to references/problems.md, which exists and contains it.

5 / 5

Workflow Clarity

The 8-step audit is clearly sequenced with checkpoints (validator-vs-code literal drift is a finding, "Stop. Do not edit code", quote file and line for every writer), and the fix flow plans a migration before tightening the validator plus an out-of-order test. It sits at 4 rather than 5 because there is no explicit feedback loop after a fix — e.g., run the new test or re-run the audit to confirm the problem is gone — and 3 would require missing or merely implicit checkpoints, which is not the case.

4 / 5

Progressive Disclosure

The body is a ~110-line overview with well-signaled, one-level-deep references: [references/problems.md](references/problems.md) is linked twice (problem checklist and transition helper), and that file exists and holds the bulk detail (13-problem table, helper, full Convex example, test). Content is appropriately split with no nested references, matching the 5 anchor.

5 / 5

Total

19

/

20

Passed

Description

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

An exemplary description: concrete third-person capabilities, a rich set of natural trigger phrases covering both direct requests and bug symptoms, and an explicit when-to-use clause. No fluff or over-claims.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — "Finds the implicit state machines", "Reports every state, every function that moves it, who can trigger each move, and the problems, then proposes an explicit transition map", "Report only by default" — with named field patterns (status, state, stage, phase, step) and flow locations. It matches the 5 anchor (multiple specific concrete actions, comprehensive) rather than 4, since the action coverage has no minor gaps and uses third-person voice throughout.

5 / 5

Completeness

It explicitly answers both questions: what it does (finds, reports, proposes a transition map) and when to use it, via a concrete "Use when the user says..." clause. This mirrors the 5 anchor's structure (clear what AND when with concrete trigger phrases); a 4 would require the when clause to be less explicit, which it is not.

5 / 5

Trigger Term Quality

The "Use when" clause covers natural phrases users would actually say, both direct requests ("find the implicit state machines", "audit status fields", "map the order or onboarding flow") and symptom reports ("a status bug, a skipped step, or a double run refund, payout, or email"). Coverage includes synonyms across the domain, matching the 5 anchor rather than 4, where only a few natural terms would be missing.

5 / 5

Distinctiveness Conflict Risk

The niche is distinct — auditing implicit state machines in status/stage/boolean-flag fields — with triggers unlikely to fire for other skills (security scans, general code review, doc generation). It matches the 5 anchor (clear niche with distinct triggers, minimal conflict risk) rather than 4, since even closely related audit skills would not be triggered by these phrases.

5 / 5

Total

20

/

20

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.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

waynesutton/convexskills

Path

skills/state-machines/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.