arn-infra-document-change
This skill should be used when the user says "document infra change", "infrastructure documentation", "generate runbook", "infra docs", "arn infra document", "create infra changelog", "document infrastructure", "generate infrastructure docs", "infra documentation", "create runbook", "generate changelog", "arn-infra-document-change", or wants to generate operational documentation (runbooks, architecture updates, changelogs, environment docs) from completed infrastructure changes.
86
83%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
89%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 description excels at trigger term coverage and completeness, providing an extensive list of natural phrases that would activate the skill and clearly stating both what it does and when to use it. Its main weakness is that the concrete actions are somewhat buried—the description focuses heavily on trigger phrases rather than explicitly listing the specific operations the skill performs (e.g., 'Generates runbooks, updates architecture diagrams, creates changelogs'). The description could also benefit from leading with a concise capability summary before the trigger list.
Suggestions
Lead with a concise capability statement listing specific actions (e.g., 'Generates operational documentation—runbooks, architecture updates, changelogs, and environment docs—from completed infrastructure changes.') before the trigger phrase list.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description mentions specific document types (runbooks, architecture updates, changelogs, environment docs) and the domain (infrastructure changes), but the 'what' is mostly implied through trigger phrases rather than explicitly listing concrete actions the skill performs. | 2 / 3 |
Completeness | The description explicitly answers both 'what' (generate operational documentation including runbooks, architecture updates, changelogs, environment docs from completed infrastructure changes) and 'when' (with a comprehensive list of trigger phrases and a 'Use when' equivalent via 'This skill should be used when...'). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms including many variations users would say: 'document infra change', 'generate runbook', 'infra docs', 'create infra changelog', 'infrastructure documentation', plus the programmatic identifier 'arn-infra-document-change'. These cover a wide range of natural phrasings. | 3 / 3 |
Distinctiveness Conflict Risk | The skill occupies a clear niche: generating operational documentation specifically from infrastructure changes. The combination of infrastructure + documentation types (runbooks, changelogs, architecture updates) makes it highly distinct and unlikely to conflict with general documentation or general infrastructure skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
77%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 operational skill with strong actionability and workflow clarity. The 7-step pipeline is clearly sequenced with proper validation gates, error handling, and user confirmation points. The main weaknesses are moderate verbosity (some sections could be more concise) and the inability to verify referenced bundle files, though the progressive disclosure pattern of referencing templates is sound.
Suggestions
Trim the experience-level adaptation section to a compact table rather than bullet-point descriptions of what Claude already understands about documentation verbosity levels.
Consider moving the detailed section lists for Steps 3-5 (architecture, playbook, environment docs) into reference template files similar to Steps 2 and 6, reducing the main skill's length.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably well-structured but includes some verbose sections that could be tightened. The experience-level adaptation section explains concepts Claude already understands (what 'expert' vs 'beginner' documentation means). The documentation scope summary template and step descriptions are somewhat repetitive in listing numbered items that could be more compact. | 2 / 3 |
Actionability | The skill provides highly concrete, actionable guidance: specific file paths to read, glob patterns for discovery, exact output file naming conventions, specific section counts to populate, and clear decision trees for project selection. The workflow is fully executable with specific commands and file operations. | 3 / 3 |
Workflow Clarity | The 7-step workflow is clearly sequenced with explicit checkpoints: prerequisites validation before proceeding, user confirmation before generation, and a comprehensive error handling section covering partial failures, re-run safety, and fallback behaviors. The pipeline position is clearly stated and each step has defined inputs and outputs. | 3 / 3 |
Progressive Disclosure | The skill references external templates (runbook-template.md, changelog-template.md) and experience-derivation.md appropriately, but no bundle files were provided to verify these exist. The main SKILL.md is quite long (~200 lines of substantive content) and some sections like the detailed per-step output specifications could potentially be moved to reference files. However, the structure is logical with clear section headers. | 2 / 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
- AppsVortex/arness
- Commit
1fe948f
- 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.