openspec-onboard

Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.

Quality

61%

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

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/openspec-onboard/SKILL.md

Quality

Content

70%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 content is a well-sequenced, highly actionable teaching workflow with strong validation checkpoints and exit handling. Its main weaknesses are length/redundancy and a monolithic structure with no progressive disclosure into reference files.

Suggestions

Extract the reusable command reference and artifact templates into a references/ file to reduce body length and enable one-level-deep navigation.

Trim redundant content such as the Phase 11 recap, which restates the phase list already shown in Phase 1.

Clarify the 'openspec instructions proposal' command usage and how proposal content is written to proposal.md, since that step is currently underspecified.

Dimension	Reasoning	Score
Conciseness	The body is largely efficient display templates, but at ~540 lines it is long for a tutorial skill and includes redundancy (e.g. the recap restates phases), so it could be tightened.	3 / 5
Actionability	Provides concrete commands ('openspec new change', 'openspec archive'), file paths, and ready-to-fill templates with placeholders; minor gaps such as underspecified 'openspec instructions proposal' usage.	4 / 5
Workflow Clarity	A clear 10-phase sequence with explicit PAUSE checkpoints, user-acknowledgment validation, graceful exit handling, and a guardrails section providing feedback loops for edge cases.	5 / 5
Progressive Disclosure	No bundle files exist and all phases are inlined in a single monolithic document; section headers give structure but no external references split the content, which is acceptable but not optimal for a skill this size.	3 / 5
	Total	15 / 20 Passed

Description

53%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 clearly states the skill's purpose but omits an explicit 'Use when...' trigger clause, capping completeness and trigger quality. It is mostly distinct from other skills but would benefit from concrete trigger phrases.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when onboarding to OpenSpec or running a first workflow cycle.'

Include natural trigger terms users would say, such as 'learn OpenSpec', 'OpenSpec tutorial', or 'first OpenSpec change'.

List a few more concrete actions (e.g. 'create a change, draft proposal and specs, implement tasks, archive') to raise specificity.

Dimension	Reasoning	Score
Specificity	Names the domain ('onboarding for OpenSpec') and 1-2 concrete actions ('walk through a complete workflow cycle', 'real codebase work'), but coverage is not comprehensive.	3 / 5
Completeness	Has a clear 'what' (guided onboarding through a workflow cycle) but no explicit 'Use when...' trigger clause, which caps completeness at 3 per the guidelines.	3 / 5
Trigger Term Quality	Includes some relevant natural terms like 'onboarding' and 'workflow cycle', but misses common synonyms and explicit trigger phrasing a user would naturally say.	3 / 5
Distinctiveness Conflict Risk	Targets a fairly distinct niche (OpenSpec onboarding tutorial) with low conflict risk, though the absence of explicit triggers leaves minor overlap risk with other OpenSpec skills.	4 / 5
	Total	13 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (555 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: dwmkerr/openspec-flow
Path: .claude/skills/openspec-onboard/SKILL.md
Commit: e670a56

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.