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

88%

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

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with a clearly sequenced, validated workflow and concrete templates. Its main weaknesses are conciseness (heavy repetition and verbosity) and progressive disclosure (a dangling template reference and over-inlined template content).

Suggestions

Define 'the resolved docs directory' once early and refer to it with a short alias afterward to eliminate ~30 repetitions and tighten the body.

Create the missing `templates/html-template.html` referenced in Step 3.2, or replace the dangling reference with an inline minimal template, so navigation is not broken.

Move the large README/doc templates and per-topic content guidelines into a `references/TEMPLATES.md` file and link to it from the body to improve progressive disclosure and reduce the inline footprint.

Dimension	Reasoning	Score
Conciseness	The body is substantive but padded — 'the resolved docs directory' is repeated ~30 times instead of being defined once, enforcement/explanation blocks are verbose, and the file runs ~540 lines; it avoids basic-concept padding but does not meet the 'lean, every token earns its place' bar.	2 / 3
Actionability	Provides concrete copy-paste-ready templates (README skeleton, per-topic content guidelines, navigation link order examples, the root-to-docs consolidation table) and specific commands like `mkdir -p docs-html`; the placeholders are templating variables appropriate to a generator rather than pseudocode, matching the top anchor.	3 / 3
Workflow Clarity	Clear sequenced workflow (Steps 0→5 with State A/B/C branching), an explicit mandatory review/validation step (Step 4) with feedback loops, and verification checkpoints for destructive ops ('Do NOT delete originals yet... until the review step confirms'), matching the explicit-validation anchor.	3 / 3
Progressive Disclosure	The checklists reference is well-signaled and one-level-deep, but the body inlines substantial template content that could be split out, and it references `templates/html-template.html` (Step 3.2) which does not exist in the bundle — a dangling path that breaks navigation, fitting the 'some structure but could be better organized' anchor.	2 / 3
	Total	10 / 12 Passed

Description

100%

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 concise, specific, and complete: it states concrete deliverables, includes a 'Use when' clause with natural trigger phrases, and occupies a distinct niche. It is a strong model description with no notable weaknesses.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Creates a lean README as a landing page with detailed docs pages split by topic in the configured docs directory' — matching the 'lists multiple specific concrete actions' anchor, well beyond merely naming a domain.	3 / 3
Completeness	Explicitly answers both what ('Generate and maintain project documentation...') and when via an explicit 'Use when user says...' clause with concrete triggers, satisfying the top anchor.	3 / 3
Trigger Term Quality	Provides natural user phrases — 'create docs', 'write documentation', 'update docs', 'generate readme', 'document project' — giving good coverage of terms a user would actually say, matching the high-coverage anchor.	3 / 3
Distinctiveness Conflict Risk	Occupies a clear niche (project documentation generation) with distinct triggers (create docs / generate readme) unlikely to conflict with unrelated skills, matching the 'clear niche with distinct triggers' anchor.	3 / 3
	Total	12 / 12 Passed

Validation

75%

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 — 12 / 16 Passed

Validation for skill structure

Criteria	Description	Result
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
Path: skills/aif-docs/SKILL.md
Commit: 4b943ec

Reviewed: 4 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.