workflow-plan
Planning pipeline with multi-mode routing (plan/verify/replan). Session discovery → context gathering (spawn_agent) → conditional conflict resolution → task generation (spawn_agent or N+1 parallel agents) → plan verification → interactive replan. Produces IMPL_PLAN.md, task JSONs, TODO_LIST.md.
35
33%
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 ./.codex/skills/workflow-plan/SKILL.mdQuality
Discovery
27%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description reads like internal technical documentation rather than a skill description designed for routing. While it is specific about the pipeline steps and output artifacts, it uses heavy jargon that users would never naturally say, and completely lacks explicit trigger guidance ('Use when...'). The description needs to be rewritten from the perspective of what a user would ask for, not how the system internally works.
Suggestions
Add an explicit 'Use when...' clause with natural trigger terms like 'create a plan', 'implementation plan', 'break down tasks', 'project planning', 'plan my work'.
Replace internal jargon (spawn_agent, N+1 parallel agents, multi-mode routing) with user-facing language describing the value: e.g., 'Generates implementation plans by analyzing project context, resolving conflicts, and breaking work into parallelizable tasks'.
Include common user phrasings that would trigger this skill, such as 'plan', 'todo list', 'task breakdown', 'implementation strategy', 'project roadmap'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: session discovery, context gathering, conflict resolution, task generation, plan verification, interactive replan. Also names specific outputs: IMPL_PLAN.md, task JSONs, TODO_LIST.md. | 3 / 3 |
Completeness | Describes what it does (planning pipeline steps and outputs) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also described in overly technical internal terms rather than user-facing language, pushing this to 1. | 1 / 3 |
Trigger Term Quality | Uses highly technical jargon like 'multi-mode routing', 'spawn_agent', 'N+1 parallel agents', 'conditional conflict resolution' — these are not terms a user would naturally say. Missing natural keywords like 'plan', 'create plan', 'implementation plan', 'task breakdown', 'project planning'. | 1 / 3 |
Distinctiveness Conflict Risk | The specific output artifacts (IMPL_PLAN.md, task JSONs, TODO_LIST.md) and the pipeline terminology provide some distinctiveness, but the term 'planning' is broad enough to overlap with other planning-related skills. Without clear trigger boundaries, conflict risk remains moderate. | 2 / 3 |
Total | 7 / 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 demonstrates excellent workflow design with clear multi-phase sequencing, conditional branching, and validation gates, but suffers severely from verbosity and monolithic structure. The ~400+ lines of inline JavaScript implementation details consume excessive context window budget and should be split into referenced files. Several code sections are incomplete or contain errors, reducing actionability despite the generally concrete approach.
Suggestions
Extract phase implementations into separate files (e.g., phases/phase-1-session.md, phases/phase-4-task-gen.md) and keep SKILL.md as a concise overview with the pipeline diagram and references
Fix incomplete code: define the `conflicts` variable in Phase 3, fix the syntax error in Phase 5's if condition, and replace pseudocode comments like '// Wait for CLI → conflicts[]' with actual implementation or explicit TODOs
Remove redundant content: the ASCII pipeline diagram and the Data Flow diagram convey overlapping information — keep one and cut the other
Trim session discovery logic significantly — the multi-session selection, slug generation, and folder creation code is implementation detail that doesn't need to be in the skill body
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines. It includes extensive inline code that could be in separate files, redundant ASCII diagrams (pipeline + data flow), and over-explains session discovery logic. Much of the JavaScript is implementation detail that bloats the context window without adding proportional instructional value. | 1 / 3 |
Actionability | The code examples are fairly concrete but not fully executable — Phase 3 references undefined variables (conflicts), Phase 5 has syntax errors (bare `||` in if condition), and several sections use pseudocode comments like '// Wait for CLI → conflicts[]' or '// Wait for CLI → verification report' without actual implementation. The spawn_agent/wait_agent API usage is concrete but the CLI integration (ccw cli) sections are incomplete. | 2 / 3 |
Workflow Clarity | The multi-phase pipeline is exceptionally well-sequenced with clear phase numbering, conditional branching (conflict risk gating Phase 3), explicit validation checkpoints (Plan Confirmation Gate, Phase 5 verification with 10 dimensions), backup before replan, and an error handling table. The feedback loop for verify→replan is clearly articulated. | 3 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no bundle files and no references to external documents. All implementation details, data flow diagrams, session structures, and phase implementations are inlined into a single massive file. The session structure diagram, full JavaScript implementations for all 6 phases, and the ASCII pipeline diagram should be split into separate referenced files. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
72%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 8 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (632 lines); consider splitting into references/ and linking | Warning |
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 8 / 11 Passed | |
- Repository
- catlog22/Claude-Code-Workflow
- Commit
5ff5e86
- 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.