command-reference-maintenance

Generate and validate shareable PowerShell or Bash command references from an explicitly supplied, non-sensitive command dump. Use when maintaining agent-readable command documentation, validating its JSON contract, or regenerating Markdown/JSON/YAML references without committing personal command histories, credentials, hostnames, or private filesystem paths.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

75%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 a well-structured overview that points to real bundle files and includes executable guidance plus validation checkpoints. It sits just below top marks because of a redundant opener, a bash-only example, an implicit rather than explicit retry loop, and inline rather than navigational file references.

Suggestions

Add an explicit error-recovery loop to the workflow (e.g. "If JSON validation fails, the generator removes output; review errors in the sanitized input, fix, and re-run") to raise workflow_clarity toward 5.

Show a `pwsh` generator invocation alongside the bash example so the actionability example covers both supported shells.

Replace the restated opening sentence with a leaner purpose line and tighten the safety-boundary bullets to reduce padding, improving token efficiency.

Add a short "References" section linking `scripts/generate_command_reference.py` and `references/reference.schema.json` so bundle navigation is explicit rather than inline.

Dimension	Reasoning	Score
Conciseness	Largely efficient and free of concepts Claude already knows, but the opening sentence restates the description and the four safety-boundary bullets include some explanatory padding that could be trimmed, keeping it just below a 5.	4 / 5
Actionability	Provides a concrete, copy-paste-ready generator invocation and an input-format table, but only the bash shell is shown in the example; the pwsh invocation is implied rather than illustrated, a minor gap versus full coverage.	4 / 5
Workflow Clarity	The five-step sequence includes an explicit JSON validation checkpoint (step 3) and a sensitive-data inspection checkpoint (step 4), with the generator removing failed output, but there is no explicit error-recovery loop ("if validation fails, fix and re-run") in the numbered steps.	4 / 5
Progressive Disclosure	Well-organized into clear sections with the tooling and schema correctly split into scripts/ and references/ and referenced by one-level-deep relative paths (both verified to exist), but references are signaled inline within steps rather than via explicit navigational pointers, leaving minor organization gaps.	4 / 5
	Total	16 / 20 Passed

Description

88%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 description is strong: third-person voice, explicit what-and-when structure, and concrete actions across shells and output formats. Its only soft spot is trigger-term breadth, where synonyms and file extensions would round out coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Generate and validate", "maintaining agent-readable command documentation", "validating its JSON contract", "regenerating Markdown/JSON/YAML references" — covering PowerShell/Bash and three output formats comprehensively, matching the comprehensive-coverage anchor.	5 / 5
Completeness	Explicitly answers both what ("Generate and validate shareable PowerShell or Bash command references from an explicitly supplied, non-sensitive command dump") and when ("Use when maintaining... validating... or regenerating...") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good keyword coverage with natural terms like "command references", "PowerShell", "Bash", "Markdown/JSON/YAML references", and "JSON contract", but missing synonyms and file-extension variants (e.g. .ps1, .sh) that would push it to a 5.	4 / 5
Distinctiveness Conflict Risk	Carves a clear niche around sanitized, shareable command-reference maintenance with distinct triggers, though the "regenerate Markdown/JSON/YAML references" phrasing leaves minor overlap risk with generic documentation-generation skills.	4 / 5
	Total	18 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: pvnkmnk/AgenticSelfHostSkills
Path: skills/command-reference-maintenance/SKILL.md
Commit: 0f62e6b

Reviewed: 4 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.