engram-docs-alignment

Documentation alignment rules for Engram. Trigger: Any code or workflow change that affects user or contributor behavior.

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/docs-alignment/SKILL.md

Quality

Content

86%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 is a tight, well-structured policy skill that respects the token budget and includes a concrete verification checklist. Its only soft spot is actionability around the validation step, which states what to check but not how to check it.

Suggestions

Make 'Validate examples before publishing' actionable by naming the mechanism, e.g. 'Run each command example in a clean shell and confirm it exits 0 before publishing'.

Consider ordering the Alignment Rules as a sequence (change -> update docs in same PR -> validate -> remove deprecated refs) to strengthen workflow clarity.

Optionally add a one-line 'how to verify' hint under the Verification checklist so each checkbox has an associated check method.

Dimension	Reasoning	Score
Conciseness	The body is lean with no padding and no explanation of concepts Claude already knows; every line (When to Use, four rules, four verification checkboxes) earns its place, matching the 'lean and efficient' anchor.	5 / 5
Actionability	The rules and verification checklist are concrete, checkable directives ('Endpoint names match server routes', 'Command examples execute as documented'), but 'Validate examples before publishing' leaves the how unspecified — a minor gap keeping it just below fully executable.	4 / 5
Workflow Clarity	Content is well-organized as use -> rules -> verification with an explicit checklist checkpoint, but the rules are a flat unordered list rather than a sequenced multi-step process, so it falls just short of the top anchor despite the simple-skill exception.	4 / 5
Progressive Disclosure	At under 50 lines with no need for external references (no bundle files present), the three cleanly separated sections (When to Use, Alignment Rules, Verification) satisfy the simple-skill exception for well-organized structure.	5 / 5
	Total	18 / 20 Passed

Description

57%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 well-scoped to a specific project and includes an explicit trigger clause, satisfying both 'what' and 'when'. Its main weakness is specificity — it states 'alignment rules' without naming the concrete actions the skill performs.

Suggestions

Replace the vague 'rules' framing with 2-3 concrete capabilities (e.g., 'verifies endpoint names match server routes, checks CLI examples execute as documented, flags deprecated references').

Add natural trigger phrases users would say, such as 'Use when updating APIs, CLI commands, or contributor guidance in the Engram docs'.

Keep the explicit trigger clause but tighten the 'what' so the description reads as actions rather than a noun phrase.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Documentation alignment rules for Engram') but the only action stated is the vague 'rules', with no concrete capabilities listed — matching the anchor 'Names the domain but actions are minimal or generic'.	2 / 5
Completeness	Both 'what' (documentation alignment rules for Engram) and an explicit 'when' ('Trigger: Any code or workflow change that affects user or contributor behavior') are present, though the 'what' is terse and could be more specific.	4 / 5
Trigger Term Quality	The 'Trigger:' clause supplies relevant terms ('code or workflow change', 'user or contributor behavior') but the description alone misses common variations and synonyms a user would naturally say.	3 / 5
Distinctiveness Conflict Risk	Scoping to the named 'Engram' project and the documentation-alignment niche makes it mostly distinct with minimal conflict risk, though the thin action list keeps it just short of a fully clear niche.	4 / 5
	Total	13 / 20 Passed

Validation

100%

Warnings & errors only

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: Gentleman-Programming/engram
Path: skills/docs-alignment/SKILL.md
Commit: 47f281c

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

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.