CtrlK
BlogDocsLog inGet started
Tessl Logo

cognitive-doc-design

Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.

63

Quality

74%

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

Fix and improve this skill with Tessl

tessl review fix ./internal/assets/skills/cognitive-doc-design/SKILL.md
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.

The body is an exemplary lean, actionable instruction skill: a rule table, a copy-paste doc template, focused PR-review guidance, and executable inspection commands with zero filler. The only real gap is the absence of an explicit step sequence for applying the patterns to an existing document, which keeps workflow clarity at 4.

DimensionReasoningScore

Conciseness

The body is lean throughout: a pattern table instead of prose, a copy-paste template, terse PR-review bullets, and two one-line commands. No concepts Claude already knows are explained (no "what is a README" padding), and every section adds non-obvious guidance — matching anchor 5 ("every token earns its place") rather than 4, which reserves room for trimmable over-explanation that isn't present here.

5 / 5

Actionability

The documentation-shape template is copy-paste ready with concrete placeholders, the pattern table gives specific rules ("Put the decision, action, or outcome first"), and the Commands section has executable git/gh commands. As an instruction-only skill per the scoring notes, the absence of program code is not penalized; this matches anchor 5 ("copy-paste ready... covers the common cases") rather than 4, which implies minor gaps in the concrete guidance.

5 / 5

Workflow Clarity

The template imposes a clear sequence (title → quick path → details → checklist → next step) and the template's Checklist section serves as a verification checkpoint, with the git/gh commands offering a way to inspect scope. It is not 5 because there is no explicit process for applying the patterns to an existing dense doc (no ordered steps like "read → identify the answer → restructure → verify scannability"), leaving a minor gap; it is above 3 because sequence and a checkpoint mechanism are present.

4 / 5

Progressive Disclosure

This is a single-file skill with no bundle directories; the ~72-line body is appropriately all-inline, split into six clearly headed sections that are easy to navigate, with no content that belongs in a separate reference file. It matches the guideline that a compact, well-organized, single-purpose skill with no external references scores 5 — and it avoids anchor 4's 'minor organization gaps' since section boundaries are clean and nothing is buried.

5 / 5

Total

19

/

20

Passed

Description

55%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 has an explicit, well-formed trigger clause with good natural keywords, but the capability statement is abstract — it names a goal (reduce cognitive load) rather than concrete actions, and the broad doc-writing triggers create overlap risk with general writing skills. Third person is used correctly and it is admirably concise.

Suggestions

Replace the abstract capability statement with 2-3 concrete actions, e.g. "Structure docs lead-with-the-answer, restructure existing dense docs into scannable sections, and write PR descriptions reviewers can verify quickly."

Add missing natural trigger variations users would say: "documentation", ".md files", "PR description", "design doc", "review feedback".

Sharpen distinctiveness by scoping to docs written for readers under time pressure (e.g. "for review-facing and quick-scan docs"), so it doesn't compete with general writing or formatting skills.

DimensionReasoningScore

Specificity

The description names the domain ("Design docs") but the only action stated — "reduce cognitive load" — is an abstract goal, not a concrete action like "extract", "fill", or "merge". It matches anchor 2 ("Names the domain but actions are minimal or generic") rather than 3, which requires 1-2 concrete actions, and not 1, since the domain and an outcome are explicitly named.

2 / 5

Completeness

Both parts are present: "Design docs that reduce cognitive load" states the what, and "Trigger: writing guides, READMEs, RFCs..." is an explicit when clause. It is not anchor 5 because the 'what' is a single vague capability rather than the multiple concrete actions in the anchor-5 example ("Extract text and tables from PDF files, fill forms, merge documents"), and it is clearly above anchor 3's missing/weak 'when'.

4 / 5

Trigger Term Quality

"guides, READMEs, RFCs, onboarding, architecture, or review-facing docs" gives good natural keyword coverage, including concrete artifact names users would say. It falls short of anchor 5's comprehensive synonym coverage: common variations like "documentation", "PR descriptions", "review comments", or ".md files" are missing, so it sits at anchor 4 ("Good keyword coverage; a few natural terms missing") rather than 5, but well above 3's partial coverage.

4 / 5

Distinctiveness Conflict Risk

The doc-design niche (RFCs, READMEs, review-facing docs) is somewhat specific, but "guides", "architecture", and "onboarding" overlap heavily with generic writing and documentation skills, matching anchor 3 ("Somewhat specific but could still overlap with similar skills"). Not 4, because the trigger set is broad enough that several writing/editing skills could plausibly claim the same request; not 2, because the cognitive-load framing and RFC/review-facing terms do carve out a recognizable niche.

3 / 5

Total

13

/

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
Gentleman-Programming/gentle-ai
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.