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".
66
80%
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/team-tech-debt/SKILL.mdQuality
Discovery
75%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 adequately covers what the skill does and when to use it, with a clear niche in tech debt remediation. However, it spends too much space on internal architecture details (team-worker agents, coordinator, pipeline) that don't help Claude decide when to select this skill, and the trigger term 'team tech debt' is artificial rather than matching natural user language. The description would benefit from more natural trigger terms and less implementation detail.
Suggestions
Replace architecture details ('team-worker agent architecture', 'Coordinator orchestrates pipeline') with more user-facing capability descriptions like specific types of tech debt detected (e.g., deprecated APIs, duplicated code, missing tests).
Expand trigger terms to include natural variations users would say: 'technical debt', 'code quality issues', 'refactor', 'code smells', 'legacy code cleanup', 'code maintenance'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (tech debt) and some actions (scans, assesses severity, plans and executes fixes with validation), but the description is partly about architecture ('team-worker agent architecture', 'Coordinator orchestrates pipeline') rather than concrete user-facing capabilities. It doesn't list specific types of tech debt or concrete outputs. | 2 / 3 |
Completeness | Answers both 'what' (scans codebase for tech debt, assesses severity, plans and executes fixes with validation) and 'when' (triggers on 'team tech debt'). While the trigger is explicit, it's narrow and somewhat artificial, but the explicit trigger clause is present. | 3 / 3 |
Trigger Term Quality | Includes 'tech debt' which is a natural term, and the explicit trigger 'team tech debt', but misses common variations users might say like 'technical debt', 'code quality', 'refactor', 'cleanup', 'code smell', or 'legacy code'. The trigger phrase 'team tech debt' is somewhat artificial and not what users would naturally say. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'tech debt identification and remediation' with the specific 'team tech debt' trigger phrase creates a clear niche that is unlikely to conflict with other skills. The team-worker architecture detail further distinguishes it. | 3 / 3 |
Total | 10 / 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 a multi-agent pipeline for tech debt remediation. Its strengths are the precise delegation lock, concrete spawn templates, and clear pipeline sequencing with error recovery. The main weakness is moderate verbosity — some sections (architecture diagram, model selection rationale) could be tightened without losing clarity.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly well-structured but includes some content that could be tightened — the architecture ASCII diagram, the extensive delegation lock table, and the agent coordination section are somewhat verbose. However, most content is domain-specific configuration that Claude wouldn't inherently know, so it earns its place more than typical verbose skills. | 2 / 3 |
Actionability | The skill provides concrete, executable guidance: exact spawn_agent templates with parameter names, specific tool call verdicts, precise file paths, timeout values (1800000ms), CLI commands, and named agent targeting examples. The role router logic and delegation lock are fully specified decision tables. | 3 / 3 |
Workflow Clarity | The pipeline is clearly sequenced (scan → assess → plan → fix → validate) with explicit validation at each stage. The delegation lock provides a clear checkpoint before every tool call. Error handling covers timeout recovery (STATUS_CHECK → FINALIZE → close), agent health reconciliation, and edge cases like 'scanner finds no debt'. The wait/retry pattern with specific timeouts constitutes a proper feedback loop. | 3 / 3 |
Progressive Disclosure | SKILL.md serves as a clear router/overview pointing to one-level-deep role files (roles/<name>/role.md) and specs (specs/pipelines.md). The role registry table provides a well-organized index with direct links. Domain-specific Phase 2-4 logic is appropriately deferred to role files rather than inlined. However, no bundle files were provided to verify these references exist. | 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 | |
5ff5e86
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.