agent-repo-architect

Agent skill for repo-architect - invoke with $agent-repo-architect

4.94x

Quality

Does it follow best practices?

Impact

94%

4.94x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/agent-repo-architect/SKILL.md

Quality

Discovery

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 is an extremely weak description that provides virtually no useful information for skill selection. It only names the tool and its invocation command, failing to describe any capabilities, actions, or usage triggers. Claude would have no reliable basis to select this skill from a pool of available skills.

Suggestions

Add concrete actions describing what repo-architect does, e.g., 'Analyzes repository structure, generates directory layouts, scaffolds new projects, and recommends file organization patterns.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about repository structure, project scaffolding, directory organization, folder layout, or codebase architecture.'

Remove the invocation instruction ('invoke with $agent-repo-architect') from the description since it serves operational purposes but does not help Claude decide when to select the skill.

Dimension	Reasoning	Score
Specificity	The description provides no concrete actions whatsoever. 'Agent skill for repo-architect' is entirely vague and does not describe what the skill actually does.	1 / 3
Completeness	The description fails to answer both 'what does this do' and 'when should Claude use it'. It only states it's an agent skill and how to invoke it, providing no functional or contextual information.	1 / 3
Trigger Term Quality	The only potentially relevant term is 'repo-architect', which is a tool name rather than a natural keyword a user would say. There are no natural language trigger terms like 'repository structure', 'project layout', etc.	1 / 3
Distinctiveness Conflict Risk	The description is so vague that Claude would have no basis to distinguish this skill from others. 'Agent skill' is entirely generic and 'repo-architect' gives only a faint hint at the domain without any specificity.	1 / 3
	Total	4 / 12 Passed

Implementation

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

This skill is an extremely verbose, non-actionable document that reads more like a marketing overview than an executable skill. The code examples are illustrative pseudocode mixing JavaScript syntax with MCP tool invocations in ways that aren't valid or executable. Critical workflow elements like validation, error handling, and verification are entirely absent despite the skill involving destructive multi-repo operations.

Suggestions

Replace all pseudocode blocks with actual executable commands or valid MCP tool call syntax that Claude can directly use, removing placeholder content like '[GitHub modes template]'.

Add explicit validation and verification steps after each destructive operation (e.g., verify pushed files exist, validate YAML/JSON before pushing, check branch creation succeeded before pushing files).

Cut the content by at least 60% — remove the generic 'Best Practices', 'Monitoring and Analysis', and 'Integration with Development Workflow' sections which contain no actionable specifics Claude doesn't already know.

Split into multiple files: keep SKILL.md as a concise overview with links to separate files for architecture patterns (PATTERNS.md), templates (TEMPLATES.md), and batch operations (BATCH-OPS.md).

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~300+ lines. Contains extensive boilerplate, placeholder content like '[Integration issue template]', repetitive patterns, and explanatory sections about best practices and monitoring that Claude already knows. The 'Best Practices' and 'Monitoring and Analysis' sections are entirely generic advice with no actionable specifics.	1 / 3
Actionability	Despite containing code blocks, the code is pseudocode/illustrative rather than executable — JavaScript syntax is used for MCP tool calls that aren't valid JS, file paths use '$' instead of '/', content placeholders like '[GitHub modes template]' provide no real guidance, and the forEach loop mixing JS with MCP calls is not executable. Claude cannot copy-paste and run any of this.	1 / 3
Workflow Clarity	No clear sequential workflow with validation checkpoints. The 'Batch Architecture Operations' section dumps everything into a single massive block with no error handling, no validation steps, and no feedback loops. For destructive operations like pushing files across multiple repos, there are no verification or rollback steps.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files despite the content being far too long for a single SKILL.md. Architecture patterns, templates, and batch operations could all be separate files. References at the bottom to other commands ($github sync-coordinator, etc.) are mentioned but not linked. No bundle files support the content.	1 / 3
	Total	4 / 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/claude-flow
Commit: e6dc21f

Reviewed: 4 days 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.