wiki-architect

You are a documentation architect that produces structured wiki catalogues and onboarding guides from codebases.

Quality

37%

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 ./skills/wiki-architect/SKILL.md

Quality

Content

38%Scale 1-5

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 reasonable high-level framework for generating wiki catalogues but falls short on actionability — it describes what to produce without showing concrete examples of the output format, JSON schema, or Mermaid diagrams. The workflow is sequential but lacks validation steps, and the content would benefit from a concrete example catalogue entry and an actual JSON schema definition. The duplicated 'When to Use' section is a minor quality issue.

Suggestions

Add a concrete example of the output JSON catalogue schema showing the exact structure with `items[].children[]`, `title`, `name`, `prompt`, and `children` fields — ideally a small but complete example.

Include a sample Mermaid diagram and a sample catalogue entry with real `file_path:line_number` citations to make the guidance executable rather than descriptive.

Add validation steps to the procedure, such as verifying the generated catalogue doesn't exceed nesting/children constraints and that all cited file paths actually exist.

Remove the duplicated 'When to Use' section at the bottom and consider extracting the detailed onboarding guide architecture and language detection rules into separate bundle files.

Dimension	Reasoning	Score
Conciseness	The skill is moderately efficient but includes some unnecessary elements: a duplicated 'When to Use' section, some explanatory text that Claude would already understand (e.g., explaining what layers are), and the language detection section could be more compact. However, it's not severely padded.	3 / 5
Actionability	The skill provides high-level procedural steps but lacks concrete, executable examples. There's no sample JSON output schema, no example catalogue entry, no example Mermaid diagram, and no concrete commands. The guidance is descriptive rather than executable — Claude is told to 'generate a hierarchical JSON catalogue' but never shown what one looks like.	2 / 5
Workflow Clarity	The procedure lists steps in a logical sequence (scan → detect → identify → generate → cite), but there are no validation checkpoints, no feedback loops for error cases (e.g., what if language detection fails or the repo has no README), and no verification that the output catalogue is well-formed or complete.	3 / 5
Progressive Disclosure	All content is inlined in a single file with no bundle files. The detailed onboarding guide architecture, language detection rules, and output schema specifications would benefit from being split into separate reference files. The catalogue JSON schema is referenced but never defined, which is a significant gap with no external file to point to.	2 / 5
	Total	10 / 20 Passed

Description

36%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.

The description identifies a niche (generating wiki catalogues and onboarding guides from codebases) but is too vague about concrete actions and completely lacks a 'Use when...' clause. It also uses second-person framing ('You are') which is inappropriate — descriptions should use third person voice. The language leans toward abstract role-playing ('documentation architect') rather than describing actionable capabilities.

Suggestions

Add an explicit 'Use when...' clause with trigger terms like 'document codebase', 'generate wiki', 'onboarding guide', 'project documentation', 'code walkthrough'.

Replace the role-playing framing ('You are a documentation architect') with third-person action verbs describing concrete capabilities, e.g., 'Analyzes codebase structure to generate structured wiki pages, onboarding guides, and API catalogues.'

Include natural synonyms and variations users might say, such as 'docs', 'README', 'project overview', 'code documentation', 'developer guide'.

Dimension	Reasoning	Score
Specificity	Names the domain (documentation/wiki catalogues/onboarding guides from codebases) but the actions are vague — 'produces' is generic and no concrete steps like 'analyzes directory structure', 'generates markdown pages', or 'creates API references' are mentioned.	2 / 5
Completeness	There is a vague 'what' (produces wiki catalogues and onboarding guides from codebases) but no 'when' clause at all. The absence of a 'Use when...' clause or equivalent trigger guidance caps this at 3 per the rubric, and the 'what' is itself not very concrete, placing it at 2.	2 / 5
Trigger Term Quality	Includes some relevant keywords like 'wiki', 'onboarding guides', 'codebases', and 'documentation', but misses natural user phrases like 'document my code', 'README', 'API docs', 'project overview', or file extensions. Users might say 'generate docs' rather than 'structured wiki catalogues'.	3 / 5
Distinctiveness Conflict Risk	The combination of 'wiki catalogues' and 'onboarding guides from codebases' provides some specificity, but 'documentation' is broad enough to overlap with general documentation skills, README generators, or API doc tools. It's somewhat specific but could still conflict with related skills.	3 / 5
	Total	10 / 20 Passed

Validation

90%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/wiki-architect/SKILL.md
Commit: 900c504

Reviewed: 22 minutes 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.