CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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".

Quality

73%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/openspec-onboard/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

73%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-sequenced, highly actionable guided workflow with strong validation and error-recovery branches, and the EXPLAIN/DO/SHOW/PAUSE structure makes the teaching flow unambiguous. Its main weakness is redundancy: the skill-reference table and several guardrail rules are repeated, inflating token cost without adding information. Organization within the single file is good, though nothing is split out to references.

Suggestions

Deduplicate the two near-identical skill-reference tables by defining the table once and referencing it from both the recap and the 'user just wants skill reference' exit path.

Trim the Guardrails section of rules already enforced inline per-phase (e.g., 'Keep narration light' and pause guidance), keeping only the cross-cutting rules.

Provide concrete commands for the codebase-analysis step (e.g., grep patterns for TODO/FIXME and ': any') so every phase is executable as written.

DimensionReasoningScore

Conciseness

The bulk of the length is functional display-template content, but the skill-reference table appears twice nearly verbatim (Phase 11 recap and 'User just wants skill reference'), and the Guardrails section restates per-phase rules already stated inline ('Keep narration light', pause guidance). Matches 'mostly efficient but could be tightened'; not 4 because the duplication is systemic rather than minor.

3 / 5

Actionability

Provides concrete executable commands throughout ('openspec --version', 'openspec list --json', 'openspec new change "<name>"', 'openspec instructions proposal --change "<name>" --json', 'openspec archive "<name>" --yes') plus exact display templates and resolvedOutputPath write instructions. Minor gaps keep it below 5: the codebase scanning heuristics (TODO/any-typing hunts) get no concrete commands, and 'openspec status' is cited for changeRoot without showing the initial invocation.

4 / 5

Workflow Clarity

Clear 11-phase sequence with explicit PAUSE checkpoints, preflight CLI validation, a JSON-based project root check, and genuine error-recovery branches (CLI not installed, 'root': null with separate auto-selected vs. explicit-request handling, and the 'Declared in'/'Invalid store declaration' config-error path with 'show message and fix'). Matches the anchor for explicit validation steps with feedback loops for error recovery.

5 / 5

Progressive Disclosure

No bundle files exist; the single file is well-structured with numbered phases and a consistent EXPLAIN/DO/SHOW/PAUSE pattern, and the inline templates are runtime-needed content rather than misplaced reference material. Minor organization gaps (duplicated skill tables, no split of long display scripts) match anchor 4; not 5, which requires well-signaled one-level-deep references that are absent here.

4 / 5

Total

16

/

20

Passed

Description

62%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 both what the skill does and when to use it, with explicit, natural trigger phrases. Its weaknesses are the high-level 'complete workflow cycle' phrasing that never names the actual artifacts or phases, and missing common synonym triggers like 'onboarding' or 'tutorial'. It is distinct within the OpenSpec skill family thanks to its unique invocation phrases.

Suggestions

Enumerate 2-3 concrete actions in the description, e.g. 'create a change and build its proposal, specs, design, and tasks artifacts, then implement and archive it' instead of the generic 'walk through a complete workflow cycle'.

Add natural trigger variations such as 'OpenSpec onboarding', 'OpenSpec tutorial', or 'get started with OpenSpec' so users phrasing the need informally still match.

Briefly signal that this is the guided/teaching entry point among the openspec-* skills to further reduce routing overlap with siblings like /openspec-propose.

DimensionReasoningScore

Specificity

Names the domain ("Guided onboarding for OpenSpec") and 1-2 high-level actions ("walk through a complete workflow cycle with narration and real codebase work") but never enumerates the concrete steps of the cycle (proposal, specs, design, tasks, archive). Anchor 3 fits: domain plus 1-2 concrete actions, not comprehensive; not 4 because the actions remain generic rather than 'several specific actions'.

3 / 5

Completeness

Both parts are present: a clear what ("walk through a complete workflow cycle with narration and real codebase work") and an explicit when with concrete trigger phrases ("Also use when the user says 'openspec onboard' or 'opsx onboard'"). Above anchor 4 because the when-clause is explicit rather than improvable, but below anchor 5 because the what stays general instead of listing concrete actions.

4 / 5

Trigger Term Quality

Includes genuine invocation phrases ("openspec onboard", "opsx onboard") but misses natural variations users would say such as 'onboarding', 'tutorial', 'get started with OpenSpec', or 'learn OpenSpec'. Matches 'some relevant keywords but missing common variations or synonyms'; not 4 since coverage is two exact commands rather than good broader coverage.

3 / 5

Distinctiveness Conflict Risk

The onboarding niche and unique trigger phrases ('openspec onboard', 'opsx onboard') are distinct, but the skill belongs to a family of openspec-* skills (propose, explore, apply-change, etc.) sharing the 'openspec' keyword, creating minor overlap risk with closely related skills. Matches anchor 4; not 5 because a generic 'openspec' mention could plausibly route to sibling skills.

4 / 5

Total

14

/

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

Path

skills/openspec-onboard/SKILL.md

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.