release-maintainer
Internal maintainer SOP for version bumps, release PRs, tagging, publishing, and post-publish verification in this repository.
48
52%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/release-maintainer/SKILL.mdQuality
Discovery
32%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 to cut a release, bump a version, create a release PR, tag a commit, or publish a package.'
Include common natural-language trigger variations like 'cut a release', 'new version', 'npm publish', 'semver bump', 'changelog', or 'deploy to registry'.
Replace 'Internal maintainer SOP' with more concrete action-oriented language, e.g., 'Guides the full release lifecycle: updating version numbers in package.json, opening release PRs, creating git tags, 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 should cap completeness at 2, and the 'what' is also only moderately clear, making this a weak 1-2; the lack of any 'when' guidance pushes it to 1. | 1 / 3 |
Trigger Term Quality | Includes relevant terms like 'version bumps', 'release PRs', 'tagging', 'publishing' that users might say, but misses common variations like 'cut a release', 'deploy', 'changelog', 'npm publish', 'semver', or 'new version'. The phrase 'Internal maintainer SOP' is jargon that users are unlikely to use. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of release-specific terms (version bumps, tagging, publishing) provides some distinctiveness, but 'release PRs' and 'publishing' could overlap with general PR or deployment skills. The phrase 'in this repository' scopes it somewhat but doesn't clearly differentiate from other release-related skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
72%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-organized maintainer SOP that effectively serves as an agent wrapper around a canonical release document. Its strengths are excellent progressive disclosure, concise writing that respects Claude's intelligence, and clear guardrails. Its main weaknesses are the lack of concrete executable commands for key release steps (version bump, tag, publish, verify) and missing explicit validation feedback loops for destructive operations like tagging and publishing.
Suggestions
Add concrete, copy-paste-ready commands for critical steps in the execution checklist (e.g., the exact `npm version`, `git tag`, `npm publish`, and verification commands) rather than delegating everything to the external doc.
Add explicit validate-fix-retry feedback loops for the tagging and publishing steps, since these are destructive operations (e.g., 'After `npm publish`, run `npm info agent-tty version` to confirm; if mismatch, check workflow logs before retrying').
| 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 it. | 3 / 3 |
Actionability | The preflight section includes one concrete executable command (`gh api graphql`), but the execution checklist and failure recovery sections are mostly procedural prose that delegates to an external document rather than providing copy-paste-ready commands. Key steps like version bumping, tagging, and publishing lack concrete command examples. | 2 / 3 |
Workflow Clarity | The preflight steps are clearly sequenced and the execution checklist provides a logical order, but most validation checkpoints are implicit or delegated to the external RELEASE-PROCESS.md. The failure recovery section is helpful but lacks explicit feedback loops (validate -> fix -> retry cycles) for the destructive tagging and publishing operations. | 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 a clear statement that this is not a second copy. Sections are logically organized (when to use, guardrails, preflight, execution, failure recovery) and references are one level deep and clearly signaled. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
90%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
- Commit
a05d4e5
- 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.