CtrlK
BlogDocsLog inGet started
Tessl Logo

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".

52

Quality

58%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.codex/skills/team-arch-opt/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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.

DimensionReasoningScore

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)'

DimensionReasoningScore

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

Total

10

/

11

Passed

Repository
catlog22/Claude-Code-Workflow
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.