CtrlK
BlogDocsLog inGet started
Tessl Logo

skill-maintenance

Editing conventions for files under `.claude/skills/**` (markdown style, frontmatter format, SKILL.md vs `references/` split, upstream-vendored skills). Use when creating a new skill, editing any `SKILL.md` or `references/*.md` file, refactoring a skill description, or after adding/removing a skill.

68

Quality

81%

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

75%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 well-crafted, instruction-only conventions skill: concrete limits, explicit decision checklists, save-gates with error recovery, and a genuine behavioral validation procedure. It stays lean for its scope and correctly encodes the SKILL.md vs references/ split policy, though it carries some deliberate self-restatement, lacks an executable method for its own 'measure the description' mandate, and inlines a re-summary of upstream guidance.

Suggestions

Provide an executable way to measure the folded description length (e.g., a short shell/python one-liner or a `scripts/measure_description.py` helper) instead of the abstract instruction 'count the length of the single string YAML produces'.

Trim the self-restatements: state the 1024-char hard ceiling once (the 'Canonical guidelines' section already cross-references 'Token economy', so the duplicate limit statement can be reduced to the cross-reference), and drop the 'Do not refactor pre-emptively' paragraph that repeats the preceding bullet's 'only length-based trigger' rule.

Move the upstream 'Canonical guidelines (Anthropic)' highlights summary into a `references/upstream-guidelines.md` file and keep a one-line pointer plus the link in SKILL.md, since the body's own policy is to push verbose material to references.

DimensionReasoningScore

Conciseness

The body is rule-dense and assumes Claude's competence (no basic-concept explanations), but has minor over-explanation that could be trimmed: the em-dash section restates the ASCII rule ('This line restates it because they slip in through copy-paste'), the 1024-char limit appears in both 'Token economy' and 'Canonical guidelines' (with an explicit cross-reference), the upstream best-practices link appears twice, and the 'Do not refactor pre-emptively' paragraph restates the preceding bullet. This fits anchor 4 ('efficient; minor instances of over-explanation that could be trimmed') rather than 3 because each restatement is deliberate and explicitly justified in the text, and rather than 5 because the duplication is real token cost.

4 / 5

Actionability

Concrete, executable rules throughout: 'Wrap markdown at **100 characters**', 'Only `name` and `description` fields', 'Use the YAML folded block scalar (`>-`)' with a yaml example, 'confirm it is under 1024', 'leave its file untouched' for vendored `humanizer`, and a validation procedure naming a fresh subagent on `opus` prompted with a trigger phrase. This fits anchor 4 ('mostly executable guidance... with minor gaps'); it is not 5 because some actions lack an executable method — 'measure it before saving: count the length of the single string YAML produces' gives no command (e.g., a one-liner) to actually measure, and the trigger-coverage test offers no concrete procedure.

4 / 5

Workflow Clarity

The editorial workflows carry explicit checkpoints and feedback loops: the after-edit checklist ('Add triggers... Remove triggers... Tighten triggers... State explicitly that no change is needed'), the save gate ('A description that reaches 1024 chars is a broken skill. Do not save it; summarize or cut triggers until it fits'), and validation ('prompt a Coding Agent... with a trigger phrase, and confirm the skill loads'). This is anchor 4 ('clear sequence with most checkpoints present; minor validation gaps'); it is not 5 because the document is a distributed conventions reference rather than one coherent end-to-end sequence, and the non-editorial sections (markdown style, frontmatter, vendored skills) are rules without sequence.

4 / 5

Progressive Disclosure

The body (~173 lines) is well under the ~500-line ceiling, self-contained with clear section headers, and explicitly encodes the split policy ('Push to `references/<topic>.md`: Setup, install, troubleshooting...'). No bundle files exist (no `references/`, `scripts/`, or `assets/`), so scoring follows the body's own structure: anchor 4 ('good structure; most content is appropriately placed; minor organization gaps'). It is not 5 because the 'Canonical guidelines (Anthropic)' section re-summarizes upstream material that could itself live in a reference file, and not 3 because nothing large is wrongly inlined and navigation by section is easy.

4 / 5

Total

16

/

20

Passed

Description

87%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: third-person, well under the 1024-char ceiling, with a clear WHAT sentence listing concrete coverage areas and an explicit multi-trigger 'Use when...' clause naming real file paths. Trigger vocabulary is natural and distinctive; only minor synonym coverage (e.g., 'update'/'write') is missing.

DimensionReasoningScore

Specificity

The WHAT sentence names the domain ('Editing conventions for files under `.claude/skills/**`') and lists four concrete coverage areas ('markdown style, frontmatter format, SKILL.md vs `references/` split, upstream-vendored skills'). This matches the anchor 'lists several specific actions; minor gaps' rather than 3 (only 1-2 concrete actions) and falls short of 5 because the items are topic areas rather than fully enumerated actions (e.g., 'validating a skill change' from the body is not surfaced).

4 / 5

Completeness

It explicitly answers both parts: WHAT ('Editing conventions for files under `.claude/skills/**` (markdown style, frontmatter format, ...)') and WHEN with a concrete 'Use when...' trigger list. This matches the 5 anchor ('clearly and explicitly answers both what AND when with concrete trigger phrases'); it cannot be 4 because the 'when' is explicit, multi-trigger, and specific, not merely 'could be more explicit'.

5 / 5

Trigger Term Quality

Triggers are natural user phrasings with file extensions: 'creating a new skill, editing any `SKILL.md` or `references/*.md` file, refactoring a skill description, or after adding/removing a skill'. Good coverage but a few natural variations are missing (e.g., 'write', 'update', or 'review a skill'), so it fits anchor 4 ('good keyword coverage; a few natural terms missing') rather than 5's 'comprehensive coverage... including synonyms'.

4 / 5

Distinctiveness Conflict Risk

The niche is clear and narrow (maintenance of `.claude/skills/**` files) with distinct file-pattern triggers (`SKILL.md`, `references/*.md`, 'adding/removing a skill') that no generic markdown or editing skill would claim. This matches the 5 anchor ('clear niche with distinct triggers; minimal conflict risk') and is above 4 because overlap risk with other skills is negligible, not just minor.

5 / 5

Total

18

/

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
SRombauts/SQLiteCpp
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.