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

Optimize this skill with Tessl

npx tessl skill review --optimize ./.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 is a solid documentation architecture guide that clearly defines document responsibilities and separation of concerns using effective tables and directory structures. Its main weaknesses are the lack of executable/actionable workflows (e.g., step-by-step processes for common documentation tasks) and missing validation tooling or commands. The content would benefit from concrete workflow sequences and verification steps rather than just declarative rules.

Suggestions

Add a concrete step-by-step workflow for common tasks like 'Adding a new vendor directory' or 'Updating README after adding a feature' with explicit validation checkpoints.

Include executable validation commands or scripts (e.g., a link-checking command, a grep pattern for finding duplicated content) rather than just a checklist of things to verify manually.

Consider splitting vendor documentation standards and cross-reference patterns into separate referenced files to improve progressive disclosure, and ensure the referenced `references/patterns.md` actually exists in the bundle.

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 explanatory text around it is somewhat redundant. Some principles (like 'Single Source of Truth') are self-evident to Claude.	2 / 3
Actionability	The skill provides concrete directory structures, checklists, and table-based rules that are fairly actionable. However, it lacks executable examples—there are no actual commands for validation, no scripts to run for link checking, and the guidance is more policy/convention than step-by-step executable instruction.	2 / 3
Workflow Clarity	The validation guidelines section provides a checklist, which is good, 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.' No feedback loops or error recovery steps are present for the validation process.	2 / 3
Progressive Disclosure	The skill references `references/patterns.md` at the end, which is good progressive disclosure. However, no bundle files are provided to verify this reference resolves. The content itself is somewhat monolithic—the vendor documentation standards, cross-reference patterns, and validation guidelines could potentially be split into separate files for a skill of this length (~130 lines of substantive content).	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-crafted 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—e.g., specifying what 'validation' entails or what 'separation of concerns' means in this context.

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: 9d7c3dc

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