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

70%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

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

Quality

Content

50%

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

This skill provides a solid structural reference for documentation architecture with good use of tables and checklists, but it leans more toward describing what documentation should look like rather than providing actionable workflows for creating or maintaining it. The content is moderately concise but could be tightened by removing explanations of obvious concepts (what a README is for) and adding concrete step-by-step workflows for common documentation tasks.

Suggestions

Add a concrete step-by-step workflow for common tasks like 'Adding a new vendor directory' with specific commands and validation checkpoints

Remove explanatory descriptions of document purposes that Claude already understands (e.g., 'First impression. Get users started quickly.') and focus on the specific rules and constraints

Provide a complete, copy-paste-ready template for a new vendor overview.md rather than just listing section headers

Add a verification step or command to validate links and cross-references rather than just listing checks as a passive checklist

Dimension	Reasoning	Score
Conciseness	The content is reasonably well-organized with tables for quick scanning, but includes some verbose sections that could be tightened. The user vs developer content separation table is useful, but the overall document is longer than necessary—Claude doesn't need explanations of what a README or CONTRIBUTING.md is for. Some sections like 'Core Principles' describe concepts rather than instruct.	2 / 3
Actionability	The skill provides concrete guidance through tables, checklists, and file structure examples, but lacks executable commands or copy-paste-ready templates. The validation guidelines are a checklist (good) but don't include specific commands to run. The vendor documentation standards give section templates but they're partial markdown snippets rather than complete, usable templates.	2 / 3
Workflow Clarity	The validation guidelines section provides a checklist, which is helpful, but there's no clear sequenced workflow for creating or updating documentation. The skill describes what should exist but doesn't clearly sequence the steps for common tasks like 'adding a new vendor' or 'updating README after a feature change.' No feedback loops or error recovery steps are present for what could be destructive operations (e.g., restructuring docs).	2 / 3
Progressive Disclosure	The skill references `references/patterns.md` at the end, which is good progressive disclosure, but no bundle files are provided to verify this exists. The content itself is somewhat monolithic—the vendor documentation standards, cross-reference patterns, and validation guidelines could potentially be split into separate files. However, the use of tables and clear section headers provides reasonable internal organization.	2 / 3
	Total	8 / 12 Passed

Description

89%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a well-structured skill description that clearly defines its scope around repository documentation architecture with explicit trigger conditions. It names specific files and documentation concepts that make it distinctive. The main weakness is that the specific actions could be more concrete—listing tasks like 'generate table of contents', 'validate internal links', or 'structure API documentation' would strengthen specificity.

Suggestions

Add more concrete action verbs beyond 'creating, updating, reviewing'—e.g., 'enforce documentation structure, validate cross-references, generate tables of contents, apply vendor documentation templates'.

Dimension	Reasoning	Score
Specificity	Names the domain (documentation architecture) and some actions (creating, updating, reviewing), and mentions specific concepts like separation of concerns, vendor documentation standards, cross-references, and validation. However, the actions themselves are somewhat generic and the concepts listed are not fully elaborated into concrete tasks.	2 / 3
Completeness	Clearly answers both 'what' (documentation architecture covering separation of concerns, vendor documentation standards, cross-references, and validation) and 'when' (explicitly states 'Use when creating, updating, or reviewing README.md, CONTRIBUTING.md, or docs/ files').	3 / 3
Trigger Term Quality	Includes natural keywords users would say: 'README.md', 'CONTRIBUTING.md', 'docs/', 'documentation', 'cross-references', 'validation'. These are specific file names and terms a user would naturally mention when working on repository documentation.	3 / 3
Distinctiveness Conflict Risk	Clearly scoped to repository documentation files (README.md, CONTRIBUTING.md, docs/) with specific concerns like vendor documentation standards and cross-references. This is a distinct niche unlikely to conflict with general coding or other documentation skills.	3 / 3
	Total	11 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: miroapp/miro-ai
Commit: 85c2c73

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