Optimize 14 skills via tessl review (avg 24% → 92%)#81
Conversation
Ran `npx tessl skill review --optimize` on all methodology pack skills and find-skills. Key improvements: - Better descriptions with "Use when..." clauses and concrete verbs - Lowercase-hyphenated name format for consistency - Trimmed self-evident prose Claude already understands - Added executable examples and quick reference tables - Condensed verbose sections into compact tables/summaries - Fixed YAML parsing errors (unquoted colons in descriptions) Net result: -552 lines across 14 files.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (14)
📝 WalkthroughWalkthroughThis PR updates 14 SKILL.md documentation files across multiple methodology packs (collaboration, debugging, planning, testing, and meta) to standardize metadata structure, expand descriptions with additional context, and restructure content from narrative prose to structured templates and tables. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| Use `DESIGN_TEMPLATE.md` as the standard artifact for each feature. It covers: | ||
|
|
||
| ### API Design | ||
| [Interface definitions] | ||
| - **Overview** — one-paragraph summary of what is being built and why | ||
| - **Requirements** — functional and non-functional (performance, security) | ||
| - **Architecture** — component diagram and explanation | ||
| - **Data Model** — entity definitions and relationships | ||
| - **API Design** — interface definitions | ||
| - **Key Decisions** — decision table with options considered, choice made, and rationale | ||
| - **Implementation Plan** — ordered steps | ||
| - **Testing Strategy** — unit and integration test scope | ||
| - **Open Questions** — unresolved items | ||
|
|
||
| ### Key Decisions | ||
| | Decision | Options Considered | Choice | Rationale | | ||
| |----------|-------------------|--------|-----------| | ||
| | Database | PostgreSQL, MongoDB | PostgreSQL | Need ACID transactions | | ||
|
|
||
| ## Implementation Plan | ||
| 1. [First step] | ||
| 2. [Second step] | ||
| ... | ||
|
|
||
| ## Testing Strategy | ||
| - Unit tests for [X] | ||
| - Integration tests for [Y] | ||
|
|
||
| ## Open Questions | ||
| - [Question 1] | ||
| - [Question 2] | ||
| ``` | ||
| Create this file at the start of each design session and keep it updated as the design evolves. |
There was a problem hiding this comment.
🟡 Reference to non-existent DESIGN_TEMPLATE.md file
The new text at packages/core/src/methodology/packs/planning/design-first/SKILL.md:159 says "Use DESIGN_TEMPLATE.md as the standard artifact for each feature" and line 171 says "Create this file at the start of each design session". This file does not exist anywhere in the repository. An AI agent following this skill would attempt to locate or reference a file that doesn't exist, producing a confusing failure. The previous version had the design document template inline, which was self-contained.
Prompt for agents
In packages/core/src/methodology/packs/planning/design-first/SKILL.md, lines 159-171 reference a DESIGN_TEMPLATE.md file that does not exist in the repository. Either (1) create the DESIGN_TEMPLATE.md file alongside this SKILL.md with the template content that was previously inline (the old version had a full markdown template with Overview, Requirements, Design, Architecture, Data Model, API Design, Key Decisions, Implementation Plan, Testing Strategy, and Open Questions sections), or (2) revert to embedding the template inline in this SKILL.md so the skill is self-contained and an AI agent can follow it without external dependencies.
Was this helpful? React with 👍 or 👎 to provide feedback.
| Component 4: Orders table — sort, pagination, row actions | ||
| ``` | ||
|
|
||
| > For more detailed worked examples of each technique, see `EXAMPLES.md`. |
There was a problem hiding this comment.
🟡 Reference to non-existent EXAMPLES.md file
The new text at packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md:84 says "For more detailed worked examples of each technique, see EXAMPLES.md". This file does not exist anywhere in the repository. An AI agent following this skill would look for a file that isn't there. The previous version had a full worked example (Password Reset feature) inline.
Prompt for agents
In packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md, line 84 references an EXAMPLES.md file that does not exist. Either (1) create the EXAMPLES.md file alongside this SKILL.md containing the worked examples that were previously inline (e.g., the Password Reset decomposition example from the old version), or (2) remove the reference and keep at least one worked example inline so the skill is self-contained.
Was this helpful? React with 👍 or 👎 to provide feedback.
| ## Pack Organization | ||
|
|
||
| Skills should be organized into methodology packs: | ||
| Group related skills under a named pack directory. See `PACKS.md` for full pack manifest format and filesystem conventions. |
There was a problem hiding this comment.
🟡 Reference to non-existent PACKS.md file
The new text at packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:183 says "See PACKS.md for full pack manifest format and filesystem conventions." This file does not exist anywhere in the repository. An AI agent following this skill would look for a file that isn't there. The previous version had the pack manifest format (pack.json example) inline.
Prompt for agents
In packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md, line 183 references a PACKS.md file that does not exist. Either (1) create the PACKS.md file containing the pack manifest format and filesystem conventions (the old version had a pack.json example inline), or (2) remove the reference and keep the pack manifest information inline so the skill is self-contained.
Was this helpful? React with 👍 or 👎 to provide feedback.
| ## Skill Maintenance | ||
|
|
||
| ### Version Updates | ||
| See `MAINTENANCE.md` for detailed versioning policy. Quick reference: |
There was a problem hiding this comment.
🟡 Reference to non-existent MAINTENANCE.md file
The new text at packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:197 says "See MAINTENANCE.md for detailed versioning policy." This file does not exist anywhere in the repository. An AI agent following this skill would try to look up a non-existent file. This is also self-contradictory: the skill-authoring skill's own completeness test (line 176) says "Can the agent follow it without external info?" — yet the skill itself now depends on external files that don't exist.
Prompt for agents
In packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md, line 197 references a MAINTENANCE.md file that does not exist. Either (1) create the MAINTENANCE.md file with the detailed versioning policy, or (2) remove the reference. The versioning quick-reference on lines 199-202 is sufficient if MAINTENANCE.md won't be created.
Was this helpful? React with 👍 or 👎 to provide feedback.
| 1. **Why** did the API return an error? → The database query failed | ||
| 2. **Why** did the database query fail? → The connection pool was exhausted | ||
| 3. **Why** was the pool exhausted? → **ROOT CAUSE:** Missing `finally` block to close connections |
There was a problem hiding this comment.
🟡 "Five Whys" section now only demonstrates three whys
In packages/core/src/methodology/packs/debugging/root-cause-analysis/SKILL.md:32-38, the section is titled "The Five Whys Method" but the example was condensed from 5 steps down to only 3 (API error → connection pool exhausted → missing finally block). The Five Whys is a well-known methodology that specifically calls for asking "Why?" five times. Showing only 3 whys in a section named "The Five Whys" misrepresents the technique and could mislead an AI agent into stopping too early when applying it.
| 1. **Why** did the API return an error? → The database query failed | |
| 2. **Why** did the database query fail? → The connection pool was exhausted | |
| 3. **Why** was the pool exhausted? → **ROOT CAUSE:** Missing `finally` block to close connections | |
| 1. **Why** did the API return an error? → The database query failed | |
| 2. **Why** did the database query fail? → The connection timed out | |
| 3. **Why** did the connection time out? → The connection pool was exhausted | |
| 4. **Why** was the connection pool exhausted? → Connections weren't being released | |
| 5. **Why** weren't connections being released? → **ROOT CAUSE:** Missing `finally` block to close connections |
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
Summary
npx tessl skill review --optimizeon all 14 methodology pack skills + find-skillsSkills optimized
Key improvements
Root Cause Analysis→root-cause-analysis)Test plan
skillkit methodology listSummary by CodeRabbit
Release Notes
Documentation