agent-architecture

Agent skill for architecture - invoke with $agent-architecture

1.49x

Quality

57%

Does it follow best practices?

Impact

88%

1.49x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-architecture/SKILL.md

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable, packed with executable architecture templates, but it is a monolithic ~440-line document with no external references and only descriptive (non-validated) workflows. Splitting the reference material into bundle files would improve both conciseness and progressive disclosure.

Suggestions

Move the large SQL, OpenAPI, k8s, security, and scalability templates into separate reference files (e.g. references/data-architecture.md, references/api-spec.md) and summarize them in SKILL.md with one-level-deep links.

Replace the generic 'Best Practices' boilerplate with architecture-specific, non-obvious guidance, or remove it entirely since it restates knowledge Claude already has.

Add an explicit validation checkpoint to the workflow (e.g. 'Review the design against the spec and pseudocode before marking arch_complete') to give the sequence a feedback loop.

Dimension	Reasoning	Score
Conciseness	The bulk is lean, concrete template material (mermaid, SQL DDL, OpenAPI, k8s manifests, security/scalability YAML) that earns its tokens, but generic boilerplate like the 'Best Practices' list ('Design for Failure', 'Loose Coupling') restates concepts Claude already knows and could be trimmed.	2 / 3
Actionability	Provides fully executable, copy-paste-ready artifacts: real PostgreSQL DDL with partitioning, a complete OpenAPI 3.0 spec, k8s Deployment/Service manifests, and concrete component/security/scalability YAML.	3 / 3
Workflow Clarity	The Architecture phase lists five numbered steps and a deliverables list, but these are descriptive phases rather than an executable sequence; there are no validation checkpoints or validate-fix-retry feedback loops for the architecture artifacts.	2 / 3
Progressive Disclosure	No bundle files exist (references/scripts/assets absent) and the body references none, so it is correctly one level deep; however at ~440 lines it is a monolithic document whose SQL, OpenAPI, k8s, security, and scalability sections are prime candidates for separate reference files.	2 / 3
	Total	9 / 12 Passed

Description

50%

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 names the architecture domain but never states concrete capabilities or explicit use-when triggers, relying instead on an invocation token. It is functional but generic, capping completeness at 2.

Suggestions

Rewrite the description to list concrete actions, e.g. 'Designs system components and boundaries, selects technology stacks, and plans scalability and deployment architectures.'

Add an explicit trigger clause such as 'Use when designing system architecture, defining component interfaces, or planning scalability for a new system.'

Drop the meta-instruction 'invoke with $agent-architecture' from the description; the invocation mechanism is handled elsewhere, and it wastes the trigger-term budget.

Dimension	Reasoning	Score
Specificity	Names the domain ('architecture') but provides no concrete actions beyond the meta-instruction 'invoke with $agent-architecture'; it tells the user to invoke the skill rather than what the skill does, so it is not comprehensive but rises above pure vagueness.	2 / 3
Completeness	Weakly answers 'what' ('Agent skill for architecture') but offers no 'Use when...' trigger guidance; per the guidelines a missing 'Use when' clause caps completeness at 2.	2 / 3
Trigger Term Quality	Includes the relevant keyword 'architecture' and the invocation token '$agent-architecture', but lacks common natural variations a user would say ('system design', 'scalability', 'component design', 'tech selection').	2 / 3
Distinctiveness Conflict Risk	'Architecture' alone is fairly generic and could overlap with other architecture-related skills, though the explicit '$agent-architecture' handle gives it a somewhat distinct trigger.	2 / 3
	Total	8 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/claude-flow
Path: .agents/skills/agent-architecture/SKILL.md
Commit: 26c35b5

Reviewed: about 7 hours ago

Table of Contents

Discovery Implementation Validation

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.