Simulates plan mode with a teaching-first approach. Use when onboarding to a new codebase, exploring architecture, or seeking guided understanding of any project area. Produces high-level overviews with diagrams, drills into details on request, and offers follow-up exploration questions.
64
51%
Does it follow best practices?
Impact
84%
1.33xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/project-guide/SKILL.mdQuality
Discovery
67%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 has a solid structure with an explicit 'Use when' clause and reasonable specificity about its outputs (diagrams, overviews, follow-up questions). However, the opening phrase 'simulates plan mode' is jargon-like and may not match natural user language, and the trigger terms could be broader to capture more natural user phrasings. The scope ('any project area') is somewhat broad, which increases conflict risk with other skills.
Suggestions
Add more natural trigger terms users would actually say, such as 'explain the code', 'walk me through', 'how does this work', 'code tour', or 'understand this project'.
Replace 'Simulates plan mode with a teaching-first approach' with a more concrete opening like 'Teaches and explains codebase structure and architecture through guided exploration' to improve specificity and reduce jargon.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (codebase onboarding/architecture exploration) and some actions (produces overviews with diagrams, drills into details, offers follow-up questions), but 'simulates plan mode with a teaching-first approach' is somewhat vague and doesn't list multiple concrete discrete actions. | 2 / 3 |
Completeness | Clearly answers both what ('produces high-level overviews with diagrams, drills into details on request, offers follow-up exploration questions') and when ('Use when onboarding to a new codebase, exploring architecture, or seeking guided understanding of any project area') with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'onboarding', 'codebase', 'architecture', and 'guided understanding', but misses common natural variations users might say such as 'explain the code', 'how does this work', 'walk me through', 'code tour', or 'understand the project'. | 2 / 3 |
Distinctiveness Conflict Risk | The 'exploring architecture' and 'codebase understanding' triggers could overlap with general code explanation or documentation skills. The 'teaching-first approach' and 'plan mode' framing add some distinctiveness, but 'guided understanding of any project area' is broad enough to conflict with other skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a teaching philosophy manifesto than a concise, actionable skill file. While it has good structural ideas (phased exploration, templates, follow-up questions), it spends far too many tokens explaining pedagogical concepts that Claude already understands. The content would benefit greatly from being cut to roughly 1/3 its current size, moving detailed templates and techniques to supporting files, and focusing the main skill on the concrete workflow and output formats.
Suggestions
Cut the 'Teaching Philosophy', 'Adaptive Teaching Techniques', and 'Handling Complexity' sections entirely or move them to a supporting file—Claude already knows how to teach and adapt to audience levels.
Reduce the main skill to the workflow phases and output format templates, which are the actually novel and actionable parts.
Move the anti-patterns table and example session flow to a supporting file like interaction-template.md to keep the main skill lean.
Add concrete validation steps, such as 'Verify the folder structure matches by running ls or tree before presenting it' to strengthen the workflow with checkpoints.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~250+ lines, with extensive philosophical content ('Teaching Philosophy', 'Adaptive Teaching Techniques', 'Handling Complexity') that explains pedagogical concepts Claude already understands. The inspirational quote at the end, the detailed table of mental models, and lengthy anti-patterns section all pad the content significantly. Much of this is telling Claude how to teach, which it already knows. | 1 / 3 |
Actionability | The skill provides structured templates and output formats which give some concrete guidance, but it contains no executable code or commands—it's entirely instructional. The templates are useful but are more like formatting suggestions than actionable steps. The 'Quick Start' section just shows example prompts rather than concrete actions Claude should take. | 2 / 3 |
Workflow Clarity | The four-phase workflow (First Impressions → Architecture → Focused Exploration → Follow-Up Questions) provides a clear sequence, but there are no validation checkpoints or feedback loops. There's no guidance on what to do if the codebase doesn't fit the expected patterns, or how to verify that the exploration is accurate. The phases are described but transitions between them rely on user prompts rather than explicit decision criteria. | 2 / 3 |
Progressive Disclosure | The skill references two supporting files (diagram-patterns.md, interaction-template.md) which is good progressive disclosure, but the main file itself is a monolithic wall of content that could benefit from splitting. The adaptive teaching techniques, handling complexity, and anti-patterns sections could all be in supporting files, keeping the main skill leaner. | 2 / 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 | |
1e34e1c
Table of Contents
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.