team-issue
Unified team skill for issue resolution. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team issue".
60
51%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.codex/skills/team-issue/SKILL.mdQuality
Discovery
25%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 focuses heavily on internal architecture (team-worker agents, coordinator, role directories) rather than describing what the skill actually does for the user. It lacks concrete actions, natural trigger terms, and a clear explanation of when it should be selected. The description reads more like an implementation note than a skill description.
Suggestions
Replace architectural jargon with concrete actions the skill performs, e.g., 'Triages, diagnoses, and resolves team issues by coordinating specialized workers for [specific domains]'.
Add natural trigger terms users would actually say, such as 'bug', 'incident', 'outage', 'resolve', 'fix', or whatever domain-specific terms apply, instead of relying solely on 'team issue'.
Expand the 'Use when...' clause with realistic scenarios, e.g., 'Use when a user reports a cross-team issue requiring coordination across multiple domains such as [examples]'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague, abstract language like 'issue resolution', 'domain logic', 'orchestrates pipeline' without listing any concrete actions the skill performs. It describes architecture rather than capabilities. | 1 / 3 |
Completeness | It attempts to answer both 'what' (issue resolution using team-worker architecture) and 'when' (triggers on 'team issue'), but the 'what' is vague and the 'when' trigger is extremely narrow and unnatural. The trigger clause exists but is weak. | 2 / 3 |
Trigger Term Quality | The only explicit trigger is 'team issue', which is not a natural phrase users would say. Terms like 'team-worker agent architecture', 'role directories', and 'coordinator orchestrates pipeline' are internal jargon, not user-facing keywords. | 1 / 3 |
Distinctiveness Conflict Risk | 'Issue resolution' is quite generic and could overlap with many skills (bug fixing, customer support, etc.), but the specific mention of 'team-worker agent architecture' and the narrow trigger 'team issue' somewhat limits overlap, albeit artificially. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured orchestration skill with highly actionable templates, clear pipeline sequencing, and strong validation/error handling. Its main weaknesses are some content duplication (spawn templates repeated, timeout instructions duplicated) and a body that's somewhat long for a router document — some content could be offloaded to referenced specs. The Delegation Lock table is an excellent safety mechanism that clearly bounds coordinator behavior.
Suggestions
Deduplicate the Worker Spawn Template — the parallel spawn version is nearly identical to the regular one; consolidate into a single template with a note about adding agent_name for parallel instances.
Consider moving the Session Directory tree and Model Selection Guide into a referenced spec file to keep SKILL.md leaner as a routing document.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly efficient for its complexity, but includes some redundancy — the Worker Spawn Template is shown twice (regular and parallel) with near-identical content, and the timeout cascade instructions are duplicated verbatim. The Model Selection Guide table and some explanatory sections could be tightened. | 2 / 3 |
Actionability | Provides concrete, copy-paste-ready spawn_agent templates with exact parameter names, a precise Delegation Lock table with allowed/blocked tool calls, specific timeout values, named agent targeting examples, and executable patterns for batch parallelism. The guidance is highly specific and directly executable. | 3 / 3 |
Workflow Clarity | The pipeline is clearly sequenced (explore -> plan -> review -> marshal -> implement) with explicit validation checkpoints: the review-fix cycle has a max of 2 rounds with forced convergence, timeout cascades have a clear 3-step escalation (STATUS_CHECK -> FINALIZE -> close), and agent health checks reconcile orphaned tasks. The Delegation Lock acts as a pre-execution validation gate. | 3 / 3 |
Progressive Disclosure | The skill references role files (roles/coordinator/role.md, etc.) and specs (specs/pipelines.md) appropriately, but no bundle files were provided to verify these exist. The SKILL.md itself is quite long (~200 lines of dense content) and some sections like the full session directory tree and duplicated spawn templates could potentially be split into referenced files. The Role Registry table with links is well-structured for navigation. | 2 / 3 |
Total | 10 / 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 |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
Total | 10 / 11 Passed | |
- Repository
- catlog22/Claude-Code-Workflow
- Commit
227244f
- 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.