team-arch-opt
Unified team skill for architecture optimization. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team arch-opt".
57
48%
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-arch-opt/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 implementation details (team-worker agents, coordinators, pipelines, role directories) rather than describing what the skill actually accomplishes for the user. It lacks concrete actions, natural trigger terms, and clear guidance on when Claude should select it. The phrase 'architecture optimization' is too vague to be useful for skill selection.
Suggestions
Replace implementation details with concrete user-facing actions (e.g., 'Analyzes codebase architecture, identifies bottlenecks, recommends structural improvements, refactors module dependencies').
Add natural trigger terms users would actually say, such as 'refactor architecture', 'optimize code structure', 'improve system design', 'reduce coupling'.
Add an explicit 'Use when...' clause describing the scenarios that should trigger this skill, beyond just the command 'team arch-opt'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'architecture optimization' and 'domain logic' without listing any concrete actions. It describes internal implementation details (team-worker agent architecture, coordinator, pipeline) rather than what the skill actually does for the user. | 1 / 3 |
Completeness | It attempts to answer both 'what' (architecture optimization) and 'when' (triggers on 'team arch-opt'), but the 'what' is extremely vague and the 'when' is just a command trigger rather than meaningful contextual guidance about when to use the skill. | 2 / 3 |
Trigger Term Quality | The only trigger term is the artificial command 'team arch-opt', which is not a natural phrase a user 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 | The specific command trigger 'team arch-opt' provides some distinctiveness, but 'architecture optimization' is broad enough to overlap with many code refactoring, system design, or performance optimization skills. The description doesn't clarify what kind of architecture or what domain it targets. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
72%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 strong actionability through concrete templates, explicit tool permissions, and clear role delegation. Its main weakness is the lack of explicit validation checkpoints and error recovery feedback loops in the coordinator's pipeline execution sequence—the error handling table exists but is disconnected from the workflow steps. The content is moderately concise for its complexity but could trim some sections like the model selection rationale.
Suggestions
Add an explicit numbered coordinator workflow sequence with validation checkpoints between pipeline stages (e.g., 'After analyzer completes, validate architecture-report.md exists and is non-empty before spawning designer').
Consolidate the model selection guide into a single line or note since all roles use 'high' reasoning effort, eliminating the redundant per-role rationale column.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly long and includes some sections that could be more compact (e.g., the session directory tree, the full spawn template, model selection rationale column). However, most content is reference-style tables and templates that serve a purpose for a complex multi-agent orchestration skill, so it's not egregiously verbose. | 2 / 3 |
Actionability | The skill provides concrete, copy-paste-ready spawn_agent templates with exact parameter structures, explicit tool call allow/block lists, specific CLI commands, named agent targeting examples, and precise file paths. The delegation lock table is immediately actionable. | 3 / 3 |
Workflow Clarity | The architecture diagram and role registry clearly show the pipeline flow (analyze -> design -> refactor -> validate -> review), and the delegation lock provides explicit validation of coordinator behavior. However, the actual multi-step pipeline execution sequence lacks explicit validation checkpoints between stages—there's no clear 'if analysis fails, do X' or 'validate before proceeding to design' feedback loop at the coordinator level. | 2 / 3 |
Progressive Disclosure | The skill is well-structured as a router/overview that delegates to role-specific files (roles/<name>/role.md) and references specs (specs/pipelines.md). References are one level deep, clearly signaled in the Role Registry table with direct links, and the SKILL.md itself serves as the coordination hub without burying details. | 3 / 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
0f8e801
- 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.