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 ./.agents/skills/openspec-onboard/SKILL.md

Quality

Content

65%

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-sequenced, actionable onboarding walkthrough with concrete OpenSpec commands and templates, but it carries teaching-style padding and keeps everything inline with no validation checkpoints for the code-mutating steps.

Suggestions

Add a verification checkpoint in Phase 9 (Apply), e.g. run the project's tests or 'openspec verify --change <name>' before archiving, to satisfy the workflow_clarity feedback-loop expectation.

Tighten or remove concept restatements (e.g. the 'elevator pitch' and 'WHEN/THEN makes requirements testable' asides) and the decorative ASCII-box placeholder to improve conciseness.

Consider moving the command reference table and the artifact templates into a referenced reference file to give SKILL.md a leaner overview and improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	Concrete commands like 'openspec new change "<derived-name>"' and 'openspec archive "<name>"' earn their place, but explanatory asides such as 'Specs define what we're building in precise, testable terms' and decorative ASCII boxes restate concepts Claude already knows; it is mostly efficient but could be tightened, matching the score-2 anchor rather than the lean score-3 anchor.	2 / 3
Actionability	The body provides copy-paste-ready commands ('openspec status --json 2>&1 \|\| echo "NOT_INITIALIZED"', 'openspec instructions proposal --change "<name>" --json') plus concrete proposal/spec/design/tasks templates and specific codebase-scan patterns (TODO/FIXME, ': any', 'console.log'), matching the score-3 anchor of fully executable guidance with specific examples.	3 / 3
Workflow Clarity	The Preflight -> Phase 1-11 sequence is clearly ordered with explicit PAUSE checkpoints and an EXPLAIN/DO/SHOW structure, but the implementation and artifact-saving phases lack validation/verification loops (no 'run tests' or 'confirm save succeeded' step); per the rubric, missing feedback loops for code-mutating/batch operations caps workflow clarity at 2.	2 / 3
Progressive Disclosure	No references/scripts/assets bundle exists, so everything (~520 lines including a full command reference and four artifact templates) lives inline in SKILL.md; sections are well-organized, but content that could be split out (e.g. the command reference table) is inline with no signaled one-level-deep references, matching the score-2 anchor rather than the score-3 clear-overview-with-references pattern.	2 / 3
	Total	9 / 12 Passed

Description

57%

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 cleanly identifies its niche (OpenSpec onboarding) but is told in an abstract, noun-phrase style that omits concrete actions and any explicit 'Use when' trigger, leaving the what/when framing incomplete.

Suggestions

Add a 'Use when ...' clause with explicit triggers, e.g. 'Use when the user wants to learn OpenSpec, get started, or run their first change cycle.'

Enumerate concrete actions in the description, e.g. 'create a change, draft proposal/specs/design/tasks, implement, and archive' instead of the generic 'walk through a complete workflow cycle'.

Include natural user variations such as 'first run', 'tutorial', or 'get started with OpenSpec' to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	Quotes 'Guided onboarding for OpenSpec' and 'walk through a complete workflow cycle with narration and real codebase work' name the domain and a couple of actions, but 'workflow cycle' is abstract and the concrete sub-actions (create change, proposal, specs) are not enumerated; closest to the score-2 anchor 'Names domain and some actions, but not comprehensive' rather than score 3 which expects multiple specific concrete actions.	2 / 3
Completeness	It answers 'what' (guided onboarding through a workflow cycle) but the 'when' is only implied by the word 'onboarding' with no 'Use when...' clause; per the rubric guideline a missing explicit trigger clause caps completeness at 2.	2 / 3
Trigger Term Quality	The terms 'onboarding' and 'OpenSpec' are natural keywords a user might say, but common variations like 'get started', 'learn OpenSpec', or 'first run' are absent, matching the score-2 anchor of 'Some relevant keywords but missing common variations'; it does not reach score 3's broad coverage.	2 / 3
Distinctiveness Conflict Risk	The phrase 'Guided onboarding for OpenSpec' ties the skill to a specific named tool and a specific first-run purpose, giving it a clear niche unlikely to trigger for unrelated skills; it matches the score-3 anchor of 'Clear niche with distinct triggers'.	3 / 3
	Total	9 / 12 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 (530 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: fengshao1227/ccg-workflow
Path: .agents/skills/openspec-onboard/SKILL.md
Commit: 9eaff79

Reviewed: about 15 hours 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.