CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

aif-docs

Generate and maintain project documentation. Creates a lean README as a landing page with detailed docs pages split by topic in the configured docs directory. Use when user says "create docs", "write documentation", "update docs", "generate readme", or "document project".

Quality

76%

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

Quality

Content

62%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 delivers a genuinely clear and well-validated workflow with concrete templates and strong safety gates, but it is bloated by duplicated policy sections and dialog transcripts, and its bundle wiring has a real defect (the missing HTML template file). Consolidating the cross-cutting policy text into references would meaningfully improve token efficiency and structure.

Suggestions

Deduplicate the skill-context precedence rules, which are stated in full both in the 'Shared project-skill-context' preamble and again in Step 0 — keep one authoritative statement and reference it.

Fix the broken `templates/html-template.html` reference: either ship the template file in the bundle or inline a minimal template so the --web flow is executable.

Move the editorial/writing-profile policy details (Step 0 and Step 2.4) into references/WRITING-PROFILE.md and keep only activation criteria in the body; shorten the example AskUserQuestion transcripts to their option lists.

DimensionReasoningScore

Conciseness

The ~570-line body noticeably duplicates material: skill-context precedence rules appear both in the 'Shared project-skill-context' preamble and again in full in Step 0, and the editorial/writing-profile policy is explained in both Step 0 and Step 2.4; long AskUserQuestion transcripts pad the flow further. This goes beyond the 'could be tightened' level of a 3 — several sections are redundant or padded.

2 / 5

Actionability

Mostly executable guidance: copy-paste-ready README and doc-page templates, a concrete scattered-file mapping table, and explicit navigation-link examples. Not a 5 because Step 3 gives no implementation for markdown-to-HTML conversion and references `templates/html-template.html`, which does not exist in the bundle.

4 / 5

Workflow Clarity

Clear state machine (A/B/C) with well-sequenced steps, a mandatory review step with an explicit 'Meaning preservation: PASS or FAIL' gate and a fix-and-repeat feedback loop, and deletion safety requiring user approval plus git-based recovery. Matches the top anchor with explicit validation steps, error-recovery loops, and a checklist reference.

5 / 5

Progressive Disclosure

The two main references (REVIEW-CHECKLISTS.md, WRITING-PROFILE.md) are clearly signaled and one level deep, but the body inlines heavy policy content (skill-context mechanics, editorial profile rules, full dialog transcripts) that belongs in reference files, the writing/ profiles nest a second level via WRITING-PROFILE.md, and the referenced `templates/html-template.html` is missing from the bundle. Structure exists but organization gaps exceed the 'minor' level of a 4.

3 / 5

Total

14

/

20

Passed

Description

83%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 that clearly states what the skill does and when to use it, with natural trigger phrases and concrete capability framing. Its only weaknesses are minor: slightly incomplete capability coverage and a few broad trigger terms with mild overlap risk.

DimensionReasoningScore

Specificity

Lists several concrete actions — 'Creates a lean README as a landing page with detailed docs pages split by topic in the configured docs directory' — going beyond a generic 'generate documentation' claim. Not a 5 because the description omits capabilities the body covers (auditing existing docs, consolidating scattered files, HTML generation), leaving minor coverage gaps.

4 / 5

Completeness

Explicitly answers both questions: the 'what' (lean README landing page plus topic-split docs pages) and the 'when' ('Use when user says...') with five concrete trigger phrases. Matches the top anchor; the 'when' clause is explicit rather than implied, so 4 does not fit.

5 / 5

Trigger Term Quality

Five natural, quotable trigger phrases ('create docs', 'write documentation', 'update docs', 'generate readme', 'document project') that users would genuinely say. Not a 5 because common variants like 'add documentation', 'make a README', or 'improve the docs' are missing.

4 / 5

Distinctiveness Conflict Risk

The README-as-landing-page plus docs-directory structure is a distinct, recognizable niche. Not a 5 because broad triggers like 'update docs' and 'document project' could plausibly fire for general writing or documentation-adjacent skills.

4 / 5

Total

17

/

20

Passed

Validation

75%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 12 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (595 lines); consider splitting into references/ and linking

Warning

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

relative_links

Relative link issues: 18 missing, 4 suspicious

Warning

Total

12

/

16

Passed

Repository

lee-to/ai-factory

Path

skills/aif-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.