CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

64

Quality

76%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/arn-infra/skills/arn-infra-document-change/SKILL.md
SKILL.md
Quality
Evals
Security

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 users might say and clearly stating both what the skill does and when to use it. Its main weakness is that the specificity of capabilities could be improved by listing more concrete actions beyond 'generate operational documentation'. The description is functional and effective for skill selection despite being somewhat trigger-term-heavy relative to capability detail.

Suggestions

Add more specific concrete actions describing what the skill does, e.g., 'Analyzes Terraform/CloudFormation changes, extracts ARN details, and generates runbooks, architecture diagrams updates, changelogs, and environment documentation.'

DimensionReasoningScore

Specificity

The description mentions specific document types (runbooks, architecture updates, changelogs, environment docs) and the domain (infrastructure changes), but it doesn't list concrete actions beyond 'generate operational documentation'. It lacks detail on what specific operations are performed (e.g., 'analyzes Terraform state changes', 'extracts ARN details').

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' (provides an extensive list of trigger phrases and a general 'Use when' clause about generating operational documentation from infrastructure changes).

3 / 3

Trigger Term Quality

Excellent coverage of natural trigger terms including many variations: 'document infra change', 'infrastructure documentation', 'generate runbook', 'infra docs', 'create infra changelog', 'document infrastructure', 'generate infrastructure docs', 'create runbook', 'generate changelog'. These are terms users would naturally say.

3 / 3

Distinctiveness Conflict Risk

The skill occupies a clear niche at the intersection of infrastructure changes and documentation generation. The specific trigger terms like 'arn-infra-document-change', 'infra changelog', and 'runbook' are highly distinctive and unlikely to conflict with generic documentation or generic infrastructure skills.

3 / 3

Total

11

/

12

Passed

Implementation

62%

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 workflow skill with clear sequencing, good error handling, and appropriate user interaction points. Its main weaknesses are moderate verbosity (some sections could be more concise) and a lack of concrete output examples — the skill describes what to generate but doesn't show sample outputs or executable snippets. The referenced template files are not available in the bundle, making it hard to assess whether the progressive disclosure is fully functional.

Suggestions

Add a concrete example of at least one generated artifact (e.g., a sample changelog entry or runbook excerpt) so Claude has a clear output target rather than just section lists.

Trim the experience-level adaptation section to a compact table rather than prose descriptions — Claude understands what 'concise' vs 'detailed' documentation means.

Provide the referenced bundle files (runbook-template.md, changelog-template.md, experience-derivation.md) or inline their key structures so the skill is self-contained enough to execute.

DimensionReasoningScore

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 clear step sequences and specific file paths/patterns (e.g., glob patterns, output paths), but lacks executable code examples. The instructions describe what to generate at a high level (e.g., 'Generate a runbook following the template structure') without showing concrete output examples or exact formatting. It references external templates but no bundle files are provided to verify their content.

2 / 3

Workflow Clarity

The workflow is clearly sequenced across 7 steps with explicit decision points (project selection, user confirmation before proceeding). Error handling is comprehensive with specific failure modes and recovery paths. The prerequisite checks form a validation gate before work begins, and the re-running safety note addresses idempotency.

3 / 3

Progressive Disclosure

The skill references external templates (runbook-template.md, changelog-template.md) and experience-derivation.md, which is good progressive disclosure design. However, no bundle files are provided to verify these references exist. The main file itself is quite long (~200 lines of content) with detailed section listings for each artifact that could potentially be moved to reference files.

2 / 3

Total

9

/

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
AppsVortex/arness
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.