CtrlK
BlogDocsLog inGet started
Tessl Logo

agent-architecture

Agent skill for architecture - invoke with $agent-architecture

55

1.49x
Quality

33%

Does it follow best practices?

Impact

88%

1.49x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

42%Weight 40%Scale 1-5

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

The body is well-structured as a template gallery but weak as an agent skill: it pads the context with ~300 lines of generic, partially corrupted example artifacts while giving the agent no executable workflow for the Architecture phase — no steps for consuming the pseudocode from memory, validating the design, or handing off deliverables. The genuine guidance (phase steps, deliverables, best practices) is about 60 lines and could carry the skill with the templates moved to references/ files. Fixes are mechanical: repair the '$'-for-'/' corruption, split the templates into reference files, and add an explicit phase workflow with entry/exit checkpoints.

Suggestions

Fix the systematic corruption in the code blocks where '$' replaces '/' (e.g., 'application$json', 'apps$v1', 'POST $auth$login', 'https:/$api.example.com$v1') so the OpenAPI, Kubernetes, and interface examples are actually usable.

Move the boilerplate templates (SQL DDL, OpenAPI spec, Kubernetes manifests, security/scalability YAML) into references/ files (e.g., references/templates.md) and keep only a short annotated example inline, cutting the body by ~60%.

Add an explicit phase workflow with checkpoints: retrieve pseudocode from memory, design each layer, validate the design against the specification (e.g., every component maps to a requirement, every interface has a contract), then store the 'arch_complete' handoff — currently these steps are only implied by the hooks.

DimensionReasoningScore

Conciseness

Roughly 300 of the ~470 lines are generic template artifacts (a boilerplate auth microservice, users/sessions/audit DDL, an OpenAPI login spec, a stock Kubernetes Deployment, caching/sharding YAML) that Claude can already produce unaided — heavily padded relative to the guidance actually needed. Matches anchor 2 ('noticeably verbose; several unnecessary explanations or padded sections') — not 1 because there is no prose explaining known concepts, not 3 because the volume of inline boilerplate is far beyond 'some unnecessary explanation'.

2 / 5

Actionability

Concrete guidance exists (the phase's five activities, named deliverables such as 'System Design Document' and 'Sequence Diagrams', and complete-looking output templates), but the operative instruction reduces to 'design architectures' with no executable workflow for producing those deliverables. It also cannot score 4 because the example code blocks are corrupted — 'application$json', 'apps$v1', 'POST $auth$login', 'https:/$api.example.com$v1', '1000$sec' use '$' where '/' belongs, so none of the OpenAPI, k8s, or SQL examples are copy-paste usable. Not 2 because the templates and deliverables list do give real, specific shape to the output.

3 / 5

Workflow Clarity

A sequence is present — the Architecture phase 'transforms algorithms into system designs' via steps 1–5 (components → interfaces → technology → scalability → deployment) with a deliverables list — but the checkpoints are entirely implicit: there is no guidance on consuming the pseudocode retrieved by the pre-hook, no validation of the produced design, and no handoff step (e.g., what the post-hook's memory_store of 'arch_complete' should contain). Matches anchor 3 ('steps listed but validation gaps; sequence present but checkpoints missing or implicit').

3 / 5

Progressive Disclosure

The body has good section structure (numbered 'High-Level Architecture' through 'Scalability Design', plus 'Architecture Deliverables' and 'Best Practices'), but it is a monolith: the SQL DDL, OpenAPI spec, and Kubernetes manifests are exactly the content that belongs in references/ files, and no references/ directory or signaled external files exist at all. Matches anchor 3 ('some structure... content that should be separate is inline') — not 2 because headers and organization are clear, not 4 because nothing is split out or navigable via references.

3 / 5

Total

11

/

20

Passed

Description

25%Weight 40%Scale 1-5

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 is effectively a placeholder: it names the domain and how to invoke the agent but says nothing about what the skill actually does, when to use it, or how it differs from other skills. It reads closer to the rubric's bad examples ('Helps with documents') than to any good example. A rewrite stating concrete capabilities (design system architecture, interfaces, deployment/scalability plans from specifications and pseudocode) plus an explicit 'Use when...' trigger clause is needed.

Suggestions

State the concrete capabilities, e.g.: 'Designs scalable system architectures — component boundaries, interfaces and contracts, technology selection, and deployment/scalability plans — from specifications and pseudocode.'

Add an explicit trigger clause, e.g.: 'Use when the user asks to design, review, or document system architecture, choose a tech stack, or plan for scalability.'

Include distinguishing trigger terms (SPARC architecture phase, system design, component/interface design, tech stack selection) so the skill is not confused with generic design or coding skills.

DimensionReasoningScore

Specificity

The description 'Agent skill for architecture - invoke with $agent-architecture' names the domain but describes no concrete capability — the only action is the meta-instruction to invoke the agent itself. It sits between anchor 1 (no concrete actions) and anchor 2 (domain named, actions minimal/generic); not 1 because it does name the domain and give an invocation command, not 3+ because there is no 'what it does' beyond the domain label.

2 / 5

Completeness

Has only a vague 'what' ('Agent skill for architecture' — it never states it designs system architectures, interfaces, or deployment plans) and no 'when' clause whatsoever; the missing-'Use when' cap of 3 applies and it falls to anchor 2 ('vague what and no when'). Not 1 because the domain and invocation are stated; not 3 because the 'what' is a domain label, not a clear capability statement.

2 / 5

Trigger Term Quality

The only natural keyword is 'architecture'; there are no trigger phrases or synonyms a user would actually say ('design the system architecture', 'tech stack', 'scalability', 'component design'). Matches anchor 2 ('one or two generic keywords; missing the natural phrases users say') — not 3 because even common variations are absent, not 1 because 'architecture' is a relevant, naturally-occurring term.

2 / 5

Distinctiveness Conflict Risk

'Architecture' is a very broad term with high overlap risk against design, planning, scaffolding, and code-review skills, and nothing in the description (e.g., SPARC methodology, system design, deliverables) narrows the niche. Matches anchor 2 ('very broad; high overlap risk') — not 3 because no distinct trigger differentiates it from similar skills.

2 / 5

Total

8

/

20

Passed

Validation

100%

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/ruflo
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.