write-openspec-docs

Switches into OpenSpec docs-writing mode; loads the house style guide and drafts or revises pages in its voice (action-first, no preamble, scannable). Use when writing or editing pages in the OpenSpec docs tree.

Quality

90%

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

92%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 an information-dense, opinionated docs-writing guide with concrete anchor examples, a clear sequenced workflow, and explicit validation backstops. Progressive disclosure is exemplary, with a lean overview pointing to clearly labeled one-level-deep references.

Dimension	Reasoning	Score
Conciseness	Dense, opinionated guidance with no generic-concept padding and every rule earning its place, but a few justifying clauses ("expanding a spare page is cheap, cutting a bloated one is a rewrite") are rationale rather than instruction and could be trimmed.	4 / 5
Actionability	Concrete, executable guidance with specific anchor examples (code fence, numbered bold lead-in, `Term: fact` bullet, table, file tree) and named exemplar files to match; fully actionable for an instruction-only skill, which the rubric does not penalize for lacking code.	5 / 5
Workflow Clarity	Clear sequence (load no-ai-slop, read writing.md, read target page, draft, run two backstop tests, report) with explicit validation feedback loops ("Retrievability", "The glance", "A failure means a slot got written without being earned; fix it now").	5 / 5
Progressive Disclosure	Concise overview with well-signaled, one-level-deep references to separate files for detail (writing.md as "the style authority", full-process.md for the deep drafting session, exemplar paths under docs-lab), matching the score-5 anchor.	5 / 5
	Total	19 / 20 Passed

Description

87%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 uses correct third-person voice and cleanly answers both what and when with a concrete trigger clause. It is specific and distinctive, with only minor gaps in action enumeration and synonym coverage.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions ("loads the house style guide and drafts or revises pages"), but the "in its voice (action-first, no preamble, scannable)" qualifier is stylistic rather than a distinct action, leaving minor coverage gaps versus a fully comprehensive action list.	4 / 5
Completeness	Explicitly answers both what ("Switches into OpenSpec docs-writing mode; loads the house style guide and drafts or revises pages") and when ("Use when writing or editing pages in the OpenSpec docs tree") with concrete trigger phrases, matching the score-5 anchor.	5 / 5
Trigger Term Quality	Multiple natural terms a user would say ("writing", "editing", "pages", "docs tree", "OpenSpec") go beyond the single-phrase score-3 anchor; a few common synonyms are missing but coverage is good.	4 / 5
Distinctiveness Conflict Risk	Tightly scoped to the OpenSpec docs niche with distinct, specific triggers; minimal overlap risk with other skills.	5 / 5
	Total	18 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 4 missing	Warning

	Total	14 / 16 Passed

Repository: Fission-AI/OpenSpec
Path: .agents/skills/write-openspec-docs/SKILL.md
Commit: 9d4e597

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