documentation-structure

Documentation architecture for this repository. Use when creating, updating, or reviewing README.md, CONTRIBUTING.md, or docs/ files. Covers separation of concerns, vendor documentation standards, cross-references, and validation.

Quality

79%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/documentation-structure/SKILL.md

Quality

Content

75%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-structured, actionable reference for documentation organization with concrete templates, directory trees, and validation checklists. The main gap is duplication between the SKILL.md body and the patterns.md reference, which violates the skill's own single-source-of-truth principle.

Suggestions

De-duplicate the body and references/patterns.md: the Related-section format and validation checklists appear in both. Keep one authoritative copy and link to it (the skill's own 'Single Source of Truth' rule).

Add a complete copy-paste README.md or CONTRIBUTING.md skeleton template so the guidance is fully executable rather than described section-by-section.

Turn the static validation checklist into an explicit validate->fix->retry feedback loop to lift workflow clarity, since documentation edits are batch-like changes.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with tables, directory trees, and terse rules; minor redundancy where the User-vs-Developer table is restated in the bullet list below it. Not 5 because of that duplicated restatement.	4 / 5
Actionability	Concrete, actionable guidance for an instruction-only skill: required file lists, a full docs/ directory tree, standard overview.md section headers, link-format examples, and validation checklists. Not 5 because no complete copy-paste README/CONTRIBUTING template is provided.	4 / 5
Workflow Clarity	Clear responsibilities per document plus a sequenced Quick Start pattern (Choose -> Install -> Authenticate -> Try) and pre-commit validation checklists (Content/Link/Format). Not 5 because validation is a static checklist without an explicit validate->fix->retry feedback loop.	4 / 5
Progressive Disclosure	Well-organized into clear sections with a one-level-deep bundle reference (references/patterns.md, verified to exist) signaled in the See Also section. Not 5 because content is duplicated between the body and patterns.md (Related-section format and validation checklists appear in both), which the skill's own 'Single Source of Truth' rule warns against.	4 / 5
	Total	16 / 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 with explicit 'what' and 'when' clauses in third-person voice and concrete file-name triggers. Minor gains available from adding more specific action verbs and synonym coverage.

Dimension	Reasoning	Score
Specificity	Names concrete actions 'creating, updating, or reviewing README.md, CONTRIBUTING.md, or docs/ files' and topic coverage (separation of concerns, vendor standards, cross-references, validation); falls short of 5 because the verbs are somewhat generic to documentation rather than highly specific concrete operations.	4 / 5
Completeness	Explicitly answers both 'what' (documentation architecture covering separation of concerns, vendor standards, cross-references, validation) and 'when' ('Use when creating, updating, or reviewing README.md, CONTRIBUTING.md, or docs/ files') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural file-name triggers 'README.md, CONTRIBUTING.md, or docs/ files' with .md extensions are terms users actually say, plus natural verbs 'creating, updating, or reviewing'; not 5 because coverage of synonyms is limited (e.g., no generic 'documentation' phrasing).	4 / 5
Distinctiveness Conflict Risk	Scoped to specific repo documentation files (README.md, CONTRIBUTING.md, docs/) giving a distinct niche; not 5 because the broad 'documentation' domain could still overlap with other doc-oriented skills.	4 / 5
	Total	17 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 2 missing, 1 deeper-than-1-level, 2 suspicious	Warning

	Total	15 / 16 Passed

Repository: miroapp/miro-ai
Path: .agents/skills/documentation-structure/SKILL.md
Commit: b6408e1

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