agent-release-swarm

Agent skill for release-swarm - invoke with $agent-release-swarm

2.94x

Quality

33%

Does it follow best practices?

Impact

100%

2.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-release-swarm/SKILL.md

Quality

Content

38%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 rich in command examples but structurally broken: duplicated frontmatter, systematically corrupted file paths/URLs that make the code non-executable, heavy redundancy across sections, and dangling references with no bundle files. It reads as generated reference material rather than a lean, actionable skill overview.

Suggestions

Fix the systematic path corruption ('$' in place of '/') throughout the code blocks and resolve ':owner/:repo' placeholders so the gh and ruv-swarm commands are actually executable.

Split the body into reference files (e.g. references/release-config.md, references/ci-workflow.md, references/release-notes-template.md) and create the referenced workflow-automation.md / multi-repo-swarm.md files, keeping SKILL.md as a concise overview with well-signaled one-level-deep links.

Deduplicate the changelog/version/release command sequences (currently repeated across 'Release Planning', 'Release Orchestration', and 'Changelog Agent') into one canonical workflow with explicit validation checkpoints before publish/deploy steps, and remove the stray second frontmatter block from the body.

Dimension	Reasoning	Score
Conciseness	The ~540-line body re-implements the same changelog/version/release gh + ruv-swarm command sequences in at least three sections ('Release Planning', 'Release Orchestration', 'Changelog Agent'), inlines a 40-line release-notes template, and pads with platitudinous 'Best Practices' bullets ('Regular release cycles', 'Clear communication') Claude already knows. It is mostly commands rather than concept explanations, which keeps it above the severely-verbose anchor, but a stray duplicated frontmatter block (name/tools/hooks, lines 6-43) sits in the body where it earns no tokens.	2 / 5
Actionability	Concrete commands dominate ('npx ruv-swarm github release-plan --analyze-commits --suggest-version', 'gh release create v2.0.0 --draft'), but as written they are not executable: URLs and paths are corrupted ('$' in place of '/', e.g. 'repos/:owner/:repo$compare/', 'actions$checkout@v3'), ':owner/:repo' placeholders are never resolved, and gh calls mix '--jq' filters with '--search' incorrectly. The ruv-swarm CLI flags are undocumented assumptions, closer to pseudocode than copy-paste-ready commands.	3 / 5
Workflow Clarity	An implied sequence exists (plan -> version -> build -> test -> deploy -> monitor) and the GitHub Actions workflow shows ordered steps, but there is no single ordered procedure with checkpoints; 'Publish release after validation' references validation that is never wired into the flow, and batch/destructive operations (npm/docker publish, production deploy, rollback) lack explicit validation gates. Per the rubric's cap for batch operations without validation, this cannot exceed 3.	3 / 5
Progressive Disclosure	The skill is monolithic: config-file templates, CI workflow YAML, agent descriptions, integration examples, and a release-notes template are all inlined in SKILL.md with no references/, scripts/, or assets/ directories present. The only external links ('See also: [workflow-automation.md](.$workflow-automation.md), [multi-repo-swarm.md](.$multi-repo-swarm.md)') point at files that do not exist and use corrupted paths — buried, broken references rather than well-signaled navigation.	2 / 5
	Total	10 / 20 Passed

Description

28%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 meta-text about how to invoke the skill rather than a statement of what it does or when to use it. It names the domain but provides no actions, no trigger conditions, and relies on the undefined jargon term 'release-swarm'.

Suggestions

State the skill's capabilities concretely in third person, e.g. 'Orchestrates software releases: generates changelogs from merged PRs, suggests semantic versions, builds multi-platform artifacts, and deploys to npm, Docker, and GitHub.'

Add an explicit trigger clause: 'Use when the user asks to cut a release, publish a version, generate a changelog, or coordinate a multi-repo or hotfix deployment.'

Remove the meta invocation text ('Agent skill for release-swarm - invoke with $agent-release-swarm') and the undefined jargon term; also deduplicate the conflicting second frontmatter block in the body so a single accurate description survives.

Dimension	Reasoning	Score
Specificity	The description 'Agent skill for release-swarm - invoke with $agent-release-swarm' names a domain ('release-swarm') but states zero concrete actions; 'invoke with $agent-release-swarm' is a tooling instruction, not a capability. It sits between the entirely-vague anchor (1) and the domain-plus-actions anchors (3+), matching anchor 2 ('Names the domain but actions are minimal or generic') at its floor.	2 / 5
Completeness	The 'what' is vague to the point of circularity (the skill is described as being 'for release-swarm', which is itself undefined) and there is no 'when' or 'Use when...' trigger clause whatsoever, matching anchor 2 ('Has a vague what and no when') and respecting the rubric cap for missing trigger guidance.	2 / 5
Trigger Term Quality	'release' is the only natural keyword embedded in the jargon token 'release-swarm'; the phrases a user would actually say ('changelog', 'publish a release', 'deploy', 'version bump', 'hotfix', 'rollback') are all absent. One generic keyword with the natural phrases missing matches anchor 2.	2 / 5
Distinctiveness Conflict Risk	The release-orchestration niche is somewhat specific, so it would not collide with arbitrary skills, but with no stated capabilities or triggers it cannot be distinguished from other release-automation or deployment skills — matching anchor 3 ('Somewhat specific but could still overlap with similar skills').	3 / 5
	Total	9 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (588 lines); consider splitting into references/ and linking	Warning
relative_links	Relative link issues: 2 missing, 1 suspicious	Warning

	Total	14 / 16 Passed

Repository: ruvnet/ruflo
Path: .agents/skills/agent-release-swarm/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.