deepinit
Deep codebase initialization with hierarchical AGENTS.md documentation
33
28%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/deepinit/SKILL.mdQuality
Discovery
17%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 too terse and jargon-heavy to serve as an effective skill selector. It lacks concrete actions, natural user-facing trigger terms, and any explicit 'when to use' guidance. The mention of AGENTS.md provides some distinctiveness but is insufficient to compensate for the other weaknesses.
Suggestions
Add a 'Use when...' clause with natural trigger terms like 'onboard to a new codebase', 'understand project structure', 'generate documentation for a repository', or 'create AGENTS.md'.
List specific concrete actions such as 'scans directory structure, identifies key modules, generates hierarchical AGENTS.md files describing each component's purpose and conventions'.
Include natural keywords users might say, such as 'explore codebase', 'project overview', 'repo documentation', 'code map', or 'new project setup'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain ('codebase initialization') and a specific artifact ('hierarchical AGENTS.md documentation'), but doesn't list concrete actions like 'scans directories', 'generates summaries', or 'maps dependencies'. | 2 / 3 |
Completeness | Provides a vague 'what' but completely lacks a 'when' clause or any explicit trigger guidance. There is no 'Use when...' or equivalent, which per the rubric caps completeness at 2, and the 'what' itself is weak enough to warrant a 1. | 1 / 3 |
Trigger Term Quality | Uses technical jargon like 'hierarchical AGENTS.md documentation' and 'deep codebase initialization' which are not terms users would naturally say. Missing natural triggers like 'onboard', 'explore codebase', 'understand project structure', 'document repository'. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of 'AGENTS.md' is fairly distinctive and narrows the scope, but 'deep codebase initialization' is vague enough to overlap with general code exploration, documentation generation, or onboarding skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides a thorough and well-structured workflow for generating hierarchical AGENTS.md documentation, with clear sequencing and validation steps. However, it is excessively verbose—packing full templates, two complete example outputs, edge case tables, and performance tips into a single file that could be cut by 60%+ through better progressive disclosure and trusting Claude's existing knowledge. The pseudo-API task syntax reduces actionability since it's not directly executable.
Suggestions
Extract the full AGENTS.md template and both example outputs into separate referenced files (e.g., TEMPLATE.md, EXAMPLES.md) to dramatically reduce the main skill's token footprint.
Remove explanations of concepts Claude already knows (what AGENTS.md files are for, what barrel exports are, what CSS modules are) and focus only on the novel hierarchical tagging system and workflow.
Replace the pseudo-task syntax (Task(subagent_type=...)) with either real executable commands or clearer plain-language instructions about what each step should accomplish.
Consolidate the multiple tables (empty directory handling, smart delegation, validation checks, quality standards) into a more compact format—several of these could be simple bullet lists or omitted entirely.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~250+ lines. It includes extensive template boilerplate, two full example AGENTS.md outputs (root and nested), and detailed tables that could be significantly condensed. Much of this content (how to write markdown tables, what a barrel export is, etc.) is knowledge Claude already possesses. | 1 / 3 |
Actionability | The workflow steps are described but rely on pseudo-task syntax (e.g., `Task(subagent_type="explore", model="haiku", ...)`) that isn't a real executable API. The bash validation commands are concrete but minimal. The template and examples are detailed but the actual execution instructions are more descriptive than executable. | 2 / 3 |
Workflow Clarity | The 5-step workflow is clearly sequenced (map → plan → generate level-by-level → compare/update → validate), with explicit ordering constraints (parent before child), a validation step with a corrective action table, and a merge strategy that preserves manual sections. The feedback loop for update mode is well-defined. | 3 / 3 |
Progressive Disclosure | Everything is in a single monolithic file with no references to supporting documents. The full template, two complete example outputs, empty directory handling, parallelization rules, quality standards, and performance considerations are all inline. Much of this content (examples, templates, edge cases) should be split into separate referenced files. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
90%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
- Yeachan-Heo/oh-my-claudecode
- Commit
679b418
- Reviewed
Table of Contents
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.