Unified team skill for tech debt identification and remediation. Scans codebase for tech debt, assesses severity, plans and executes fixes with validation. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team tech debt".
76
71%
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-tech-debt/SKILL.mdQuality
Discovery
57%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 identifies a clear domain (tech debt) and lists some concrete actions, but dilutes its effectiveness by including implementation architecture details (team-worker agents, coordinator, pipeline) that don't help Claude decide when to select this skill. The trigger term coverage is narrow, missing common synonyms users would naturally use, and the 'when to use' guidance is minimal despite having a trigger phrase.
Suggestions
Replace architecture details ('team-worker agent architecture', 'coordinator orchestrates pipeline') with a proper 'Use when...' clause listing scenarios like 'when the user asks about technical debt, code quality issues, legacy code cleanup, or code smell remediation'.
Add natural trigger term variations such as 'technical debt', 'code smells', 'refactoring', 'legacy code', 'code quality', and 'cleanup' to improve matching against diverse user requests.
Reframe the trigger from the narrow 'Triggers on "team tech debt"' to a broader set of conditions that would naturally lead a user to need this skill.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (tech debt) and some actions (scans codebase, assesses severity, plans and executes fixes with validation), but also includes implementation details about architecture (team-worker agent, coordinator, pipeline) that don't describe user-facing capabilities. The concrete actions are present but mixed with internal design details. | 2 / 3 |
Completeness | The 'what' is partially covered (scans, assesses, plans, fixes). There is a trigger phrase ('Triggers on "team tech debt"'), but it's narrow and not framed as a proper 'Use when...' clause with broader guidance on when to select this skill. The trigger guidance is minimal rather than explicit and comprehensive. | 2 / 3 |
Trigger Term Quality | Includes 'tech debt' as a key term users might say, and mentions 'team tech debt' as a trigger phrase. However, it misses natural variations like 'technical debt', 'code quality', 'refactor', 'legacy code', 'code smell', or 'cleanup' that users would commonly use. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'tech debt identification and remediation' with the specific trigger 'team tech debt' creates a clear niche. The team-worker architecture mention and specific domain focus make it unlikely to conflict with other skills like general code review or refactoring skills. | 3 / 3 |
Total | 9 / 12 Passed |
Implementation
85%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-crafted orchestration skill that clearly defines the team-worker architecture, provides concrete spawn templates and tool policies, and sequences the multi-stage pipeline with appropriate validation. The progressive disclosure is excellent with a clean router pattern pointing to role-specific files. Minor verbosity in some sections (model selection rationale, agent health pseudocode) could be trimmed without losing clarity.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly well-structured and avoids explaining basic concepts, but it includes some verbose sections (e.g., the full Delegation Lock table, the Agent Health Check pseudocode, and the Model Selection Guide rationale column) that could be tightened. The architecture diagram and multiple tables add bulk but most earn their place for a complex orchestration skill. | 2 / 3 |
Actionability | Provides concrete spawn_agent templates with exact parameters, specific tool call allowlists/blocklists, exact CLI commands, precise file paths, timeout values (1800000ms), and named agent targeting examples. The delegation lock table gives unambiguous verdicts for every tool category. | 3 / 3 |
Workflow Clarity | The pipeline is clearly sequenced (scan → assess → plan → fix → validate) with explicit validation at each stage. The timeout handling has a clear escalation path (STATUS_CHECK → FINALIZE with interrupt → mark timed_out → close). The Delegation Lock serves as a validation checkpoint preventing the coordinator from doing work directly. Error handling table covers edge cases. | 3 / 3 |
Progressive Disclosure | SKILL.md serves as a clear router/overview with well-signaled one-level-deep references to roles/<name>/role.md files and specs/pipelines.md. The Role Registry table provides a complete index with direct links. Content is appropriately split between the overview (architecture, routing, shared constants) and role-specific files. | 3 / 3 |
Total | 11 / 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 | |
227244f
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.