release-maintainer

Internal maintainer SOP for version bumps, release PRs, tagging, publishing, and post-publish verification in this repository.

Quality

52%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/release-maintainer/SKILL.md

Quality

Content

72%Scale 1-3

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

This is a well-structured maintainer SOP that efficiently serves as an agent wrapper around a canonical release process document. Its main strength is conciseness and clear progressive disclosure, avoiding duplication while adding agent-specific guardrails and failure recovery. Its main weakness is that actionability suffers from delegating most concrete commands to the external document, and the workflow lacks inline validation checkpoints for the happy path.

Suggestions

Add inline executable commands for the most critical steps (version bump, tagging, npm publish) so the skill is usable even without reading the external doc, or at minimum show the exact command patterns expected.

Add explicit validation checkpoints in the Execution Checklist (e.g., 'After tagging, verify: `git tag -v <tag>` → confirm signature; After npm publish, verify: `npm view agent-tty@<version>`') to create feedback loops for the happy path.

Dimension	Reasoning	Score
Conciseness	The skill is lean and efficient. It avoids explaining what releases are or how npm/GitHub work. Every section adds project-specific knowledge Claude wouldn't have, and it explicitly delegates to the canonical doc rather than duplicating content.	3 / 3
Actionability	The skill provides some concrete commands (e.g., the `gh api graphql` preflight check, `gh run view ... --json` for CI waiting) but most guidance is procedural prose pointing to an external document rather than providing executable, copy-paste-ready commands for each step. Key operations like version bumping, tagging, and publishing lack inline commands.	2 / 3
Workflow Clarity	There is a clear preflight sequence and an execution checklist, plus a failure recovery section with specific scenarios. However, the actual multi-step release workflow is delegated entirely to `docs/RELEASE-PROCESS.md` without inline validation checkpoints or explicit feedback loops. The failure recovery section partially compensates but the core happy-path workflow lacks explicit validate-then-proceed gates.	2 / 3
Progressive Disclosure	The skill is well-structured as an agent wrapper that clearly references the canonical `docs/RELEASE-PROCESS.md` for detailed steps, with one-level-deep references. Sections are logically organized (when to use, guardrails, preflight, execution, failure recovery) and the skill explicitly states it is not a second copy of the release recipe.	3 / 3
	Total	10 / 12 Passed

Description

32%Scale 1-3

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 identifies a clear domain (release management) and lists relevant activities, but lacks an explicit 'Use when...' clause, which significantly hurts completeness. The trigger terms are reasonable but miss common user phrasings, and the 'Internal maintainer SOP' framing uses jargon that doesn't match how users naturally request help.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about cutting a release, bumping versions, publishing packages, or creating release PRs.'

Include more natural trigger terms users would say, such as 'release', 'deploy', 'npm publish', 'semver', 'changelog', 'cut a release', 'new version'.

Replace 'Internal maintainer SOP' with more concrete action-oriented language, e.g., 'Guides the release process including updating version numbers in package.json, creating release pull requests, tagging commits, publishing to npm, and verifying published packages.'

Dimension	Reasoning	Score
Specificity	Names the domain (release management) and lists several actions (version bumps, release PRs, tagging, publishing, post-publish verification), but these are somewhat high-level categories rather than deeply concrete actions like 'update package.json version field' or 'create GitHub release tag'.	2 / 3
Completeness	Describes what the skill covers (version bumps, release PRs, etc.) but has no explicit 'Use when...' clause or equivalent trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' portion is also only moderately detailed, placing this at 1.	1 / 3
Trigger Term Quality	Includes relevant terms like 'version bumps', 'release PRs', 'tagging', 'publishing' that users might naturally say, but misses common variations like 'release', 'deploy', 'npm publish', 'changelog', 'semver', or 'cut a release'. The phrase 'Internal maintainer SOP' is jargon that users are unlikely to use.	2 / 3
Distinctiveness Conflict Risk	The release/publishing domain is somewhat specific and distinguishable from general coding skills, but terms like 'tagging' and 'publishing' could overlap with other skills (e.g., git workflows, CI/CD pipelines). The phrase 'in this repository' adds some scoping but is vague about which repository.	2 / 3
	Total	7 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: coder/agent-tty
Path: .agents/skills/release-maintainer/SKILL.md
Commit: ebff2c2

Reviewed: 1 day 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.