agent-repo-architect

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

4.94x

Quality

25%

Does it follow best practices?

Impact

94%

4.94x

Average score across 3 eval scenarios

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-repo-architect/SKILL.md

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 a well-sectioned but monolithic document: it presents multi-repo architecture workflows as pseudocode with placeholder file contents and '$'-corrupted path separators, so nothing is copy-paste executable, and batch repository operations include no validation steps. Substantial inlined template/pattern material belongs in reference files, and a stray second YAML frontmatter block inside the body is a structural defect.

Suggestions

Fix the corrupted path separators ('$' → '/') throughout all code blocks and replace placeholder contents ('[GitHub modes template]') with real file contents or a pointer to a template file, so examples become executable.

Add validation checkpoints to the batch workflows — e.g. after push_files, verify the pushed structure via gh api or check CI run status before marking todos complete — which currently cap workflow clarity.

Move the full template file payloads, directory-tree patterns, and best-practice lists into references/ files (e.g. references/templates.md, references/structure-patterns.md) linked one level deep from SKILL.md, and remove the duplicate YAML frontmatter block from the body.

Dimension	Reasoning	Score
Conciseness	The 400-line body repeats the description verbatim in 'Purpose', and sections like 'Best Practices' ('Scalable architecture for future growth', 'Comprehensive architecture documentation') and 'Monitoring and Analysis' are generic platitudes Claude already knows — several padded sections add no instruction. Not a 1 because it does not explain basic concepts at textbook length; not a 3 because the padding is pervasive rather than occasional.	2 / 5
Actionability	The usage patterns name specific MCP tools and parameters (swarm_init, push_files, create_or_update_file), which is concrete guidance, but every code block is pseudocode with placeholder content ('[Standardized CLAUDE.md template]') and corrupted paths ('.claude$commands$github$github-modes.md', 'actions$checkout@v3' — '$' where '/' belongs), so nothing is executable as written. This matches the 'pseudocode instead of executable code; missing key details' anchor.	3 / 5
Workflow Clarity	Each usage pattern does list a sequence (init swarm → spawn agents → analyze → orchestrate/push), but the workflow involves batch pushes of files across multiple repositories with zero validation or verification steps — the 'steps listed but checkpoints missing' anchor, and the batch-operation rule caps this at 3. Not a 4 because no checkpoint (e.g. verifying the pushed structure or CI result) exists anywhere.	3 / 5
Progressive Disclosure	Section headers (Usage Patterns, Architecture Patterns, Best Practices) give real structure, but all bulk detail — full template file contents, directory-tree patterns, integration patterns — is inlined in a monolithic 400-line SKILL.md with no references/ files at all, matching 'content that should be separate is inline'. Not a 2 because structure is present and clearly labeled; not a 4 because nothing is offloaded to a separate file and a stray duplicate YAML frontmatter block sits in the middle of the body.	3 / 5
	Total	11 / 20 Passed

Description

7%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 frontmatter description is a bare invocation pointer, not a capability description. It fails to say what the skill does or when to use it, and provides no natural trigger terms. Note also that the real description text ('Repository structure optimization and multi-repo management...') is buried in a duplicate, stray YAML block inside the body rather than in the actual frontmatter, which compounds the problem.

Suggestions

Replace the description with the capability text currently stranded in the stray second YAML block, e.g. 'Optimizes repository structure, coordinates multi-repo management, and standardizes templates and CI workflows. Use when restructuring a repo, setting up monorepo layouts, or synchronizing files across multiple repositories.'

Add explicit 'Use when...' trigger phrasing covering natural user terms such as 'repository structure', 'monorepo', 'repo template', and 'cross-repo synchronization'.

Remove the invocation instruction ('$agent-repo-architect') from the description and keep only the what/when statements; also delete the duplicated YAML frontmatter block inside the body so only one frontmatter remains.

Dimension	Reasoning	Score
Specificity	The description 'Agent skill for repo-architect - invoke with $agent-repo-architect' names no concrete action or capability whatsoever; it is a pure invocation pointer with abstract wrapper language, matching the 'entirely vague; no concrete actions' anchor. It is not a 2 because it does not even name the domain of work (repository architecture) — only a skill name.	1 / 5
Completeness	Neither 'what does this skill do' nor 'when to use it' is stated; the text only describes how to invoke it. This matches the 'missing both what and when' anchor exactly.	1 / 5
Trigger Term Quality	No natural keywords a user would say appear; '$agent-repo-architect' is an internal invocation token, not a phrase like 'repository structure' or 'monorepo' that a user would naturally utter. Not a 2 because there is not even one generic domain keyword present.	1 / 5
Distinctiveness Conflict Risk	The unique name 'repo-architect' gives it some distinct identity, so it is unlikely to trigger for unrelated skills, but with zero capability or trigger description it cannot be distinguished from a sibling wrapper skill; 'somewhat specific but could still overlap' fits. Not a 4 because nothing in the text itself differentiates its function from other agent-wrapper skills.	3 / 5
	Total	6 / 20 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/ruflo
Path: .agents/skills/agent-repo-architect/SKILL.md
Commit: b14c79e

Reviewed: 3 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.