CtrlK
BlogDocsLog inGet started
Tessl Logo

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".

63

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

70%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-engineered, highly actionable workflow skill with excellent sequencing and validation for its destructive/batch operations. Its weaknesses are length and repetition in the main body, over-inlining of template material, and a dangling reference to a missing templates file.

Suggestions

Move the README template, per-topic content guidelines, and the scattered-file consolidation table into a reference file (e.g. references/TEMPLATES.md), keeping SKILL.md as the workflow overview.

Add the missing templates/html-template.html to the bundle or remove the reference — Step 3 currently points to a file that does not exist.

Tighten repeated phrasing: replace the recurring "the resolved docs directory" with the concrete default `docs/` after first mention, and compress the skill-context override rules into a single statement.

DimensionReasoningScore

Conciseness

The body is mostly efficient — templates, tables, and scripted AskUserQuestion dialogs rather than prose — but at ~550 lines it carries noticeable padding: the phrase "the resolved docs directory" is repeated dozens of times where "docs/" would do, the skill-context section re-states its override rule four ways ("CRITICAL", "Enforcement", "Do NOT ignore"), and the README template is inlined in full. This fits the 'mostly efficient but could be tightened' anchor rather than the 'minor instances' one.

3 / 5

Actionability

Mostly executable guidance: full README/doc-page templates, a concrete consolidation mapping table, exact navigation-link examples per file, and commands like `mkdir -p docs-html`. Not a 5 because Step 3's markdown-to-HTML conversion is described abstractly ("parse markdown → convert to HTML elements") and depends on `templates/html-template.html`, which is not present in the bundle, leaving the --web path without a complete executable recipe.

4 / 5

Workflow Clarity

The workflow is a clearly sequenced state machine (State A/B/C with explicit sub-steps and flag-dependent routing), and risky operations get explicit validation and feedback loops: Step 4 is "MANDATORY after any content change", the split requires "Verify no content was lost", and deletion requires re-verification, user approval, and `git status` for recovery. This matches the top anchor including checklists for complex processes.

5 / 5

Progressive Disclosure

Structure exists and `references/REVIEW-CHECKLISTS.md` is a well-signaled, one-level-deep reference that is a real bundle file — but the body inlines substantial content that belongs in reference files (the full README template, per-topic content guidelines, the consolidation table), and it references `templates/html-template.html` which does not exist in the bundle. This lands on 'some structure but content that should be separate is inline' rather than 'good structure'.

3 / 5

Total

15

/

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 explicitly covers what the skill does, the documentation structure it produces, and when to invoke it via natural user phrases. Minor room to improve by mentioning the audit/split/HTML-generation capabilities and adding a few more trigger synonyms.

Suggestions

Mention 1-2 more capabilities (e.g., auditing/improving existing docs, splitting a long README) to close the specificity gap.

Add trigger synonyms such as "add docs", "make a README", or "docs page" to broaden natural-term coverage.

DimensionReasoningScore

Specificity

Concrete actions are named — "Generate and maintain project documentation" and "Creates a lean README as a landing page with detailed docs pages split by topic in the configured docs directory" — going beyond generic domain naming. Not a 5 because several real capabilities (auditing existing docs, splitting a long README, consolidating scattered files, --web HTML generation) are not mentioned, leaving minor gaps in coverage.

4 / 5

Completeness

Both questions are answered explicitly: the "what" ("Generate and maintain project documentation. Creates a lean README as a landing page with detailed docs pages split by topic") and the "when" via a literal "Use when user says..." clause with concrete trigger phrases. This matches the top anchor exactly, including the landing-page/docs-directory structural detail.

5 / 5

Trigger Term Quality

Five natural quoted trigger phrases users would actually say — "create docs", "write documentation", "update docs", "generate readme", "document project" — give good keyword coverage. Not a 5 because common variations like "make a README", "add docs", or "docs page" are missing, though the included set is natural and on-target.

4 / 5

Distinctiveness Conflict Risk

The README-landing-page-plus-docs-directory niche is distinct and the triggers are specific to documentation generation, so overlap risk is low. Not a 5 because phrases like "write documentation" and "update docs" are broad enough to also fire for generic writing or README-tweaking 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 (556 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
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.