CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

sdlc-generate-docs

Workflow for auditing, designing, and writing structured documentation based on the Diátaxis Framework (Tutorials, How-to, Reference, Explanation).

Quality

62%

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 ./.agents/skills/sdlc-generate-docs/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

52%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 core of this skill is genuinely useful — the quadrant rules, three-phase workflow, and documentation standards are concrete and well-sequenced. However, it is wrapped in persona-activation padding and redundant directives that waste context, and it never shows what its output should look like. Stripping the theatrical framing and adding per-quadrant templates would lift it substantially.

Suggestions

Delete the 'Dynamic Persona Activation' block, the session-lock rule, and the circular 'Skill Execution (Mandatory)' directive — they consume context without changing what Claude does; fold the one useful line (the persona mission) into the intro.

Add a short template or skeleton for each quadrant (e.g. the section structure of a Tutorial vs. a Reference page) so the drafting phase has concrete output shapes instead of 'clear, professional formatting'.

Consolidate the duplicated guidance: the Overview repeats When to Use, 'Strict Mode Separation' repeats the quadrant rules, and 'Reference First' restates the standards section — one canonical statement of each rule would tighten the whole file.

DimensionReasoningScore

Conciseness

The body carries several padded sections that add nothing Claude needs: the ~10-line 'Dynamic Persona Activation [CRITICAL SYSTEM OVERRIDE]' theater ('YOU ARE HEREBY COMMANDED TO STOP ACTING AS A GENERAL ASSISTANT'), the 'Session Lock Adherence' rule, the circular 'Skill Execution (Mandatory)' directive that just restates the skill's own authority, and an Overview section that repeats the When to Use list verbatim in spirit. This is noticeably verbose rather than 'mostly efficient' (anchor 3), though not the wall-of-filler of anchor 1.

2 / 5

Actionability

There is real concrete guidance — exact quoted clarification prompts, a verbatim refusal message, target folders (/docs/tutorials/, /docs/reference/), the ADR triple-gate criteria, and CONTEXT.md scope-detection steps. But key details are missing: no templates or worked examples showing what a finished Tutorial, How-to, Reference, or Explanation page looks like, and Phase 3 step 1 ('Write the content in clear, professional formatting') is the kind of vague direction anchor 3 describes. Not 4, because the gaps go beyond minor.

3 / 5

Workflow Clarity

The three phases are clearly sequenced with explicit checkpoints: the upfront Context Check Protocol, the Phase 1 clarification checkpoint, Phase 2's 'Wait for Approval' gate before drafting, and Phase 3's Domain Consistency Check and Code & Spec Traceability validations. This matches anchor 4 (clear sequence, most checkpoints present, minor gaps) — it lacks the full error-recovery feedback loops of anchor 5, e.g. what to do when terminology conflicts with CONTEXT.md or when a documented feature turns out not to exist in the codebase.

4 / 5

Progressive Disclosure

There are no bundle files (references/, scripts/, assets/ are absent), and the ~130-line body is organized into clearly labeled, navigable sections (persona, directives, quadrants, workflow, anti-patterns, standards) — good structure with minor organization gaps, matching anchor 4. It is not 5 because content that could plausibly live in one-level-deep references (the full Documentation Standards section and the four quadrant rule sets) is fully inlined, and the skill references project files like .agents/standards/CONTEXT-FORMAT.md without signaling whether they ship with the skill or are expected in the user's repo.

4 / 5

Total

13

/

20

Passed

Description

53%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 clearly states what the skill does and anchors it to a distinctive framework, but it never tells the user (or Claude) when to reach for it. Adding an explicit 'Use when...' clause with natural trigger phrases would fix the biggest gap.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user asks to create, restructure, or audit documentation, tutorials, how-to guides, reference pages, or explanations, or when organizing a /docs folder.'

Broaden natural keyword coverage with synonyms users actually say: 'docs', 'user guide', 'README', 'API reference', 'onboarding guide' — not just the four Diátaxis quadrant names.

Make the actions more concrete: e.g. 'audits existing docs for mode-mixing, classifies pages into the four Diátaxis quadrants, and drafts each quadrant in its correct voice' instead of the generic 'auditing, designing, and writing'.

DimensionReasoningScore

Specificity

The description names the domain ("structured documentation") and three actions ("auditing, designing, and writing") anchored to a specific framework, but the actions remain generic — what auditing or designing documentation concretely involves is never stated. This matches anchor 3 (domain plus actions, not comprehensive) rather than 4, which expects several genuinely specific actions with only minor gaps.

3 / 5

Completeness

The 'what' is clearly stated ("auditing, designing, and writing structured documentation based on the Diátaxis Framework"), but there is no 'Use when...' clause or equivalent explicit trigger guidance anywhere in the description. Per the judging guidelines, a missing 'Use when' clause caps completeness at 3, which also rules out 4.

3 / 5

Trigger Term Quality

It includes some relevant natural terms — "documentation", "Tutorials", "How-to", "Reference" — but misses common variations users would actually say, such as "docs", "user guide", "README", "onboarding guide", or "API reference". Coverage is partial, matching anchor 3 rather than 4 ("a few natural terms missing" would require broader coverage including synonyms).

3 / 5

Distinctiveness Conflict Risk

The explicit "Diátaxis Framework (Tutorials, How-to, Reference, Explanation)" framing carves out a clear niche that few skills share, giving minimal conflict risk with unrelated skills. It falls short of 5 only because generic terms like "documentation" and "Reference" could still overlap with general writing or README-generation skills.

4 / 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

glenrioariesto/social-content-studio

Path

.agents/skills/sdlc-generate-docs/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.