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 is heavy on internal implementation details (team-worker agents, coordinator, role directories) but extremely light on what the skill actually does for the user. It lacks natural trigger terms and concrete capability descriptions, making it difficult for Claude to know when to select this skill in a multi-skill environment.
Suggestions
Replace implementation details ('team-worker agent architecture', 'role directories', 'coordinator orchestrates pipeline') with concrete actions the skill performs, e.g., 'Analyzes codebase structure, identifies coupling issues, recommends module boundaries, and generates refactoring plans.'
Add natural language trigger terms users would actually say, e.g., 'Use when the user asks about improving code architecture, reducing technical debt, refactoring modules, or optimizing system design.'
Expand the 'when' clause beyond the single command 'team arch-opt' to include scenario-based triggers that describe user intents and contexts.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description mentions 'architecture optimization' and 'team-worker agent architecture' but never explains what concrete actions are performed. Terms like 'orchestrates pipeline' and 'domain logic' are abstract and vague—no specific capabilities (e.g., 'refactors modules', 'reduces coupling') are listed. | 1 / 3 |
Completeness | It partially addresses 'what' (architecture optimization using a team-worker pattern) and provides a trigger ('Triggers on "team arch-opt"'), but the 'what' is too vague to be useful and the 'when' is limited to a single command phrase rather than describing scenarios or user intents. | 2 / 3 |
Trigger Term Quality | The only explicit trigger is the command 'team arch-opt', which is technical jargon a user would not naturally say. There are no natural language keywords like 'optimize architecture', 'refactor', 'performance', or 'system design' that a user might use. | 1 / 3 |
Distinctiveness Conflict Risk | The specific command trigger 'team arch-opt' reduces conflict risk, but the vague domain of 'architecture optimization' could overlap with refactoring, performance tuning, or code review skills. Without clearer scope boundaries, moderate overlap risk remains. | 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 and clear progressive disclosure via role-based file organization. Its main weaknesses are moderate verbosity (some tables could be condensed) and missing explicit validation checkpoints between pipeline stages, which is important for a multi-step architecture optimization workflow involving destructive code changes.
Suggestions
Add explicit validation gates between pipeline stages (e.g., 'Only proceed to refactorer after designer plan is validated by coordinator') to make the multi-step workflow safer and clearer.
Condense the Model Selection Guide table — since all roles use 'high' reasoning effort, a single statement like 'All roles use reasoning_effort: high (architecture optimization is reasoning-intensive)' would save tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly dense and information-rich, but includes some redundancy (e.g., the delegation lock table is thorough but verbose, the model selection guide repeats 'high' for every role with similar rationale). Some sections like the session directory tree and error handling table are efficient, but overall it could be tightened. | 2 / 3 |
Actionability | Provides concrete spawn_agent templates with exact parameters, specific tool call allowlists/blocklists, exact file paths, CLI commands, and named agent targeting examples. The worker spawn template is copy-paste ready with clear placeholders. | 3 / 3 |
Workflow Clarity | The architecture diagram shows the pipeline flow (analyze -> design -> refactor -> validate -> review) and the role router logic is clear. However, the multi-step coordination workflow lacks explicit validation checkpoints between pipeline stages — there's no clear 'validate before proceeding to next phase' pattern. The timeout handling sequence is well-defined, but the overall pipeline sequencing and inter-stage validation gates are implicit rather than explicit. | 2 / 3 |
Progressive Disclosure | Excellent progressive disclosure structure: SKILL.md serves as a clear router/overview, with role-specific logic delegated to individual role.md files via a well-organized role registry table. References are one level deep, clearly signaled with relative paths, and the specs reference points to pipeline definitions. The session directory structure provides clear navigation of artifacts. | 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 | |
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.