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.

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 ./.claude/skills/openspec-onboard/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

82%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 guided walkthrough with real commands, complete artifact templates, explicit pause checkpoints, and thorough fallback handling for exits and edge cases. Its main weaknesses are minor: a duplicated command reference table, no verification step after implementation, and slightly padded scripted narration in places.

DimensionReasoningScore

Conciseness

The body is efficient for a guided tutorial: nearly every block is a concrete template, scripted message, or command rather than explanation of concepts Claude already knows (e.g. it never explains what git or specs are; the WHEN/THEN note is one line and task-specific). Minor over-explanation exists in some scripted narration ('You can literally read them as test cases', the welcome block) that could be trimmed, keeping it just below the 'lean and efficient' level-5 anchor.

4 / 5

Actionability

Guidance is fully executable: real CLI commands ('openspec status --json', 'openspec new change "<derived-name>"', 'openspec archive "<name>"'), exact file paths ('openspec/changes/<name>/proposal.md', 'specs/<capability>/spec.md'), and complete copy-paste-ready artifact templates for proposal, spec, design, and tasks covering the common cases. Placeholders like <name> are parameterization, not pseudocode, so it matches the top anchor rather than the level-4 anchor with 'minor gaps'.

5 / 5

Workflow Clarity

An 11-phase sequence with a preflight initialization check, explicit PAUSE checkpoints, and fallback/error-recovery paths (not initialized, no tasks found, oversized scope, mid-way exit) — this goes beyond the level-3 anchor. It falls short of level 5 because there is no explicit verification step after implementation (the skill mentions '/opsx:verify' in the command table but never runs it during the cycle), a minor validation gap.

4 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/), and the skill is a single continuous guided flow where inlining is mostly appropriate; sections are clearly organized (Preflight, numbered phases, Graceful Exit Handling, Guardrails). Minor organization gaps — the command reference table appears twice (Phase 11 and the quick-reference exit path) and could be consolidated or split into a reference file — keep it at 'good structure; most content appropriately placed' rather than the level-5 ideal of well-signaled one-level-deep references.

4 / 5

Total

17

/

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 communicates what the skill does and is appropriately scoped to OpenSpec, but it omits any 'when to use' trigger guidance and natural trigger phrases. Adding an explicit 'Use when...' clause with concrete user-said phrases would address its main weaknesses in completeness and trigger term quality.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user is new to OpenSpec, asks to learn/get started with OpenSpec, or wants a walkthrough of the OpenSpec workflow.'

List a few concrete actions to raise specificity, e.g. 'walks through task selection, proposal, specs, design, tasks, implementation, and archiving a change'.

Include natural synonyms users would say ('first time', 'getting started', 'tutorial', 'walkthrough') so the description matches how the need is actually expressed.

DimensionReasoningScore

Specificity

The description names the domain ('Guided onboarding for OpenSpec') and 1-2 concrete actions ('walk through a complete workflow cycle', 'real codebase work'), but does not list the several specific actions (proposal, specs, design, tasks, apply, archive) that the skill actually performs. It matches the 'names domain and 1-2 concrete actions, but not comprehensive' anchor, not the level-4 anchor which requires several listed specific actions.

3 / 5

Completeness

The 'what' is clear (guided onboarding walking through a complete workflow cycle with narration and real codebase work), but there is no 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. It cannot score 4 because 'when to use' is entirely absent, not merely implicit-but-stated.

3 / 5

Trigger Term Quality

Relevant keywords like 'onboarding', 'OpenSpec', and 'workflow cycle' are present, but common natural variations a user would say are missing ('getting started with OpenSpec', 'learn OpenSpec', 'first time', 'tutorial', 'walkthrough'). It fits the 'some relevant keywords but missing common variations or synonyms' anchor rather than the level-4 'good keyword coverage' anchor.

3 / 5

Distinctiveness Conflict Risk

The explicit 'OpenSpec' scoping gives it a clear niche with minimal conflict risk against unrelated skills, but the generic words 'onboarding' and 'workflow cycle' leave minor overlap risk with other tutorial/onboarding skills that lack a trigger clause to disambiguate. This is 'mostly distinct; minor overlap risk', one notch below the fully distinct level-5 anchor.

4 / 5

Total

13

/

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 (550 lines); consider splitting into references/ and linking

Warning

Total

15

/

16

Passed

Repository

PBH-BTN/PeerBanHelper

Path

.claude/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.