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.
68
57%
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 good structural completeness with explicit 'Use when' triggers and a clear what/when split. However, it leans on somewhat abstract concepts like 'simulates plan mode' and 'teaching-first approach' that may not match natural user language. The trigger terms could be expanded to cover more natural phrasings users would employ when seeking codebase understanding.
Suggestions
Add more natural trigger terms users would actually say, such as 'explain the code', 'walk me through', 'how does this project work', 'code tour', or 'understand this repo'.
Replace or clarify 'simulates plan mode' with more concrete language describing what the skill actually does, since 'plan mode' is jargon that may not resonate with users or help Claude distinguish this skill.
| 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 abstract and the concrete actions could be more specific. | 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'). | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'onboarding', 'codebase', 'architecture', and 'guided understanding', but misses common 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 'teaching-first approach' and 'plan mode' framing provide some distinctiveness, but 'exploring architecture' and 'guided understanding' could overlap with general code explanation or documentation skills. The niche is moderately clear but not sharply defined. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
47%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has a well-structured workflow with clear phases and output templates, but is significantly over-engineered and verbose for what it teaches. Much of the content covers general teaching and communication principles that Claude already understands (progressive disclosure, meeting learners where they are, using analogies). The referenced bundle files don't exist, undermining the progressive disclosure structure.
Suggestions
Cut the 'Teaching Philosophy', 'Adaptive Teaching Techniques', and 'Handling Complexity' sections entirely—Claude already knows how to teach and adapt to audience level. This alone would halve the document.
Remove the anti-patterns table and motivational quote; these are generic teaching advice that wastes tokens.
Either provide the referenced bundle files (diagram-patterns.md, interaction-template.md) or remove the references to avoid dead links.
Consolidate the skill to focus on the four-phase workflow with its output templates—that's the genuinely useful, actionable content.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~250+ lines, with extensive philosophical guidance ('Teaching Philosophy', 'Adaptive Teaching Techniques', 'Handling Complexity') that Claude already knows how to do. Sections like 'Core Principles' and 'Mental Model Building' explain general pedagogy concepts that don't add actionable value. The anti-patterns table and motivational quote are padding. | 1 / 3 |
Actionability | The skill provides structured templates and output formats which give some concrete guidance, but it's fundamentally an instruction-only skill about how to behave rather than executable steps. The templates are useful but are more like suggestions than copy-paste-ready artifacts. There are no concrete commands or code to execute—it's guidance on conversational style. | 2 / 3 |
Workflow Clarity | The four-phase workflow (First Impressions → Architecture Deep Dive → Focused Exploration → Follow-Up Questions) is clearly sequenced with explicit output formats for each phase. The example session flow at the end demonstrates how phases connect. For a conversational/teaching skill without destructive operations, this level of workflow clarity is appropriate. | 3 / 3 |
Progressive Disclosure | The skill references two supporting files (diagram-patterns.md and interaction-template.md) which is good structure, but neither file exists in the bundle. The main SKILL.md itself is monolithic—sections like 'Adaptive Teaching Techniques' and 'Handling Complexity' could be in separate files. Too much detail is inline for a skill of this length. | 2 / 3 |
Total | 8 / 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 | |
a5309ae
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.