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".
52
58%
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-arch-opt/SKILL.mdQuality
Discovery
40%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, role directories, coordinator/pipeline) rather than describing what the skill actually does for the user. The term 'architecture optimization' is too vague to understand the skill's purpose, and the trigger is a synthetic command rather than natural language. The description fails to communicate concrete user-facing capabilities or scenarios.
Suggestions
Replace implementation details with concrete user-facing actions (e.g., 'Analyzes codebase architecture and recommends improvements to reduce coupling, improve modularity, and optimize performance').
Add a 'Use when...' clause with natural trigger terms describing user scenarios (e.g., 'Use when the user asks about refactoring architecture, reducing technical debt, improving code structure, or optimizing system design').
Clarify the domain - specify what kind of architecture (software, system, infrastructure) to reduce ambiguity and conflict risk with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'architecture optimization' without specifying concrete actions. Terms like 'team-worker agent architecture', 'role directories', 'coordinator orchestrates pipeline' describe internal implementation details rather than user-facing capabilities. | 1 / 3 |
Completeness | The 'what' is weakly addressed ('architecture optimization') and the 'when' is provided only as a command trigger ('Triggers on "team arch-opt"') rather than describing scenarios or user needs. The trigger clause exists but is not a meaningful 'Use when...' guidance. | 2 / 3 |
Trigger Term Quality | It includes the explicit trigger phrase 'team arch-opt' which is a specific command, but this is a synthetic/technical trigger rather than natural language a user would say. There are no natural keywords describing what problem the user is trying to solve. | 2 / 3 |
Distinctiveness Conflict Risk | The specific trigger command 'team arch-opt' provides some distinctiveness, but 'architecture optimization' is broad enough to overlap with other architecture, refactoring, or optimization skills. It's unclear what domain or type of architecture this applies to. | 2 / 3 |
Total | 7 / 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 strong actionability and workflow clarity — the delegation lock, spawn templates, and timeout handling sequences are concrete and unambiguous. The main weakness is that the SKILL.md tries to be both a router/overview and a comprehensive reference, making it longer than necessary. Some inline content (session directory tree, model selection rationale, error handling tables) could be moved to referenced spec files to improve conciseness and progressive disclosure.
Suggestions
Move the detailed session directory tree and error handling table to a referenced spec file (e.g., specs/session-structure.md) to reduce SKILL.md length
Trim the model selection guide — since all roles use 'high' reasoning effort, replace the table with a single line: 'All roles use reasoning_effort: high (architecture optimization is reasoning-intensive)'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly well-structured and avoids explaining basic concepts, but it's quite long with some redundancy (e.g., the delegation lock table, model selection guide, and session directory listing are verbose). Some sections like the ASCII architecture diagram and the detailed session directory tree could be more compact. | 2 / 3 |
Actionability | The skill provides concrete, executable guidance: specific spawn_agent templates with exact parameters, precise tool call allowlists, named agent targeting examples, timeout handling sequences, and exact file paths. The delegation lock table gives unambiguous verdicts for every tool category. | 3 / 3 |
Workflow Clarity | The multi-step orchestration pipeline is clearly sequenced (analyze -> design -> refactor -> validate -> review) with explicit validation checkpoints. The timeout handling has a clear escalation sequence (STATUS_CHECK -> FINALIZE with interrupt -> mark timed_out -> close). The delegation lock provides a clear validation gate before every tool call, and error handling covers recovery scenarios. | 3 / 3 |
Progressive Disclosure | The skill references role files (roles/coordinator/role.md, etc.) and specs (specs/pipelines.md) appropriately, but the SKILL.md itself is quite long with inline content that could be delegated to referenced files. The session directory structure and error handling tables could live in separate reference files. However, no bundle files were provided to verify the referenced paths exist. | 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 | |
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.