CtrlK
BlogDocsLog inGet started
Tessl Logo

openspec-onboard

Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work. Also use when the user says "openspec onboard" or "opsx onboard".

67

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

88%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.

This is a strong instructional skill: an explicitly sequenced 11-phase workflow with validation checkpoints, error-recovery branches, graceful exits, and fully executable OpenSpec CLI commands with JSON output handling. The only notable improvements are deduplicating the command reference table and moving the artifact format templates out of the main file to trim length.

DimensionReasoningScore

Conciseness

The body is dense operational guidance — exact CLI invocations, JSON fields to read, and branching rules for store selection and root detection — with little explanation of concepts Claude already knows. The main trims available are the 8-row command reference table duplicated nearly verbatim in Phase 11 and the 'Quick Reference' exit section, and the ASCII-diagram placeholder block. Fits anchor 4 ('Efficient; minor instances of over-explanation that could be trimmed') better than 3, since the padding is localized duplication rather than a pattern of unnecessary explanation.

4 / 5

Actionability

Commands are copy-paste ready with correct JSON-reading instructions ('openspec instructions proposal --change "<name>" --json' then write to 'resolvedOutputPath', 'openspec archive "<name>" --yes' with the reason for --yes given), and each phase has verbatim display templates. Fully executable guidance covering the common cases — the anchor 5 example; it exceeds anchor 4 because even edge handling (root null, store errors, CLI missing) is concrete.

5 / 5

Workflow Clarity

Eleven clearly sequenced phases with explicit PAUSE checkpoints, a preflight CLI check, a project-setup validation step (read 'root' from 'openspec list --json', with the non-zero exit explained), and error-recovery branches for both root-null paths and mid-session exits. This matches anchor 5 ('Clear sequence with explicit validation steps; feedback loops for error recovery'), exceeding anchor 4's 'minor validation gaps' — validation is present at every risky transition.

5 / 5

Progressive Disclosure

The file is well-sectioned (Preflight, Phases 1-11, Graceful Exit, Guardrails) and self-contained with no bundle files, so there are no buried or nested references. However, at ~560 lines, material that could live in separate reference files — the artifact format templates and the command reference tables — is inlined. Fits anchor 4 ('Good structure; most content is appropriately placed... minor organization gaps') rather than 5, which expects content appropriately split across files, and clearly above 3, where structure is weak or references unclear.

4 / 5

Total

18

/

20

Passed

Description

73%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 cleanly answers what the skill does and when to use it, with a clearly distinct niche. Its weaknesses are moderate specificity (the workflow cycle's concrete stages are not named) and a narrow 'when' clause limited to two exact command phrasings rather than natural-language variations.

Suggestions

Name the concrete stages of the cycle in the description (e.g., 'create a change and build its proposal, specs, design, and tasks, implement, and archive it') so the 'what' is specific rather than abstract.

Broaden the trigger clause beyond exact command strings to natural phrasings a user would say, such as 'Use when the user wants to get started with OpenSpec, learn the OpenSpec workflow, or do their first change.'

Keep the existing 'openspec onboard' / 'opsx onboard' triggers — they are accurate — but present them as examples within the broader 'when' guidance.

DimensionReasoningScore

Specificity

The description names the domain (OpenSpec onboarding) and one concrete action ('walk through a complete workflow cycle with narration and real codebase work'), but does not enumerate the specific actions performed (proposal, specs, design, tasks, archive). It fits the anchor 'Names domain and 1-2 concrete actions, but not comprehensive' — below level 4, which requires several listed specific actions, and above level 2, since more than the bare domain is stated.

3 / 5

Completeness

Both parts are present: 'what' ('Guided onboarding... walk through a complete workflow cycle with narration and real codebase work') and an explicit 'when' ('Also use when the user says "openspec onboard" or "opsx onboard"'). The 'when' clause is explicit but narrow — only exact command phrasings — so it matches anchor 4 ('when' could be more explicit or specific) rather than 5, and clearly above 3, where 'when' is missing or only implied.

4 / 5

Trigger Term Quality

Explicit trigger phrases '"openspec onboard"' and '"opsx onboard"' are natural things a user would say, giving good keyword coverage, but common variations like 'get started with OpenSpec', 'OpenSpec tutorial', or 'first change' are missing. Fits anchor 4 ('Good keyword coverage; a few natural terms missing') rather than 5, which demands synonym and variation coverage.

4 / 5

Distinctiveness Conflict Risk

The 'OpenSpec' niche and 'onboard' trigger phrases are distinct from other skills and from OpenSpec's other subcommands (propose, explore, archive). Clear niche with distinct triggers and minimal conflict risk — the anchor 5 example; it is not merely 'mostly distinct' (anchor 4), since the onboarding purpose and its triggers are unambiguous.

5 / 5

Total

16

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (575 lines); consider splitting into references/ and linking

Warning

Total

15

/

16

Passed

Repository
Fission-AI/OpenSpec
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.