adopt

Scaffold the PKM system onto an existing Obsidian vault. Scans your vault structure, maps folders interactively, and generates configuration — no template required.

Quality

67%

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 ./vault-template/.claude/skills/adopt/SKILL.md

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with a clear, validated multi-phase workflow, but it is monolithic and somewhat verbose: Phase 3's verbatim onboard questions and full config templates are inlined where progressive disclosure to reference/script files would reduce tokens. Splitting those into bundle files would lift the two weakest dimensions.

Suggestions

Move the verbatim Phase 3 onboard questions and full option lists into a shared reference file (e.g. references/onboard-questions.md) and link to it, cutting inline bulk.

Extract the large config templates (settings.json, vault-config.json, adopt-env.sh) into scripts/ or assets/ and reference them, enabling progressive disclosure and keeping SKILL.md a lean overview.

Tighten the illustrative example outputs (the full vault-scan block and the adoption summary) to essentials rather than complete transcripts.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient procedural instruction without explaining concepts Claude already knows, but Phase 3 reproduces the four onboard questions verbatim with full option lists and the illustrative scan/summary output blocks are long; these could be tightened or delegated, matching the 'mostly efficient but could be tightened' anchor.	2 / 3
Actionability	Guidance is fully executable and copy-paste ready: concrete commands (ls/Glob/Grep exclusions), exact JSON configs (settings.json, vault-config.json), and complete shell scripts (adopt-env.sh, session-init source block), plus exact AskUserQuestion formats.	3 / 3
Workflow Clarity	Six phases are clearly sequenced with an explicit validation checkpoint in Phase 6a (read back vault-config.json, verify folders exist, CLAUDE.md non-empty, adopt-env.sh executable) and a dedicated Error Handling section covering not-a-vault, already-adopted, permission, and empty-vault cases.	3 / 3
Progressive Disclosure	Sections are well-organized into phases, but the skill is monolithic at ~250 inline lines with no bundle files (references/, scripts/, assets/ absent) and content that could be split — the verbatim onboard questions and full config templates — is kept inline, matching the 'content that should be separate is inline' anchor rather than the one-level-deep reference structure of a 3.	2 / 3
	Total	10 / 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 states concrete capabilities and carves out a distinct niche, but it lacks an explicit 'Use when' trigger clause and slips into second-person voice, which together cap completeness and specificity. Adding a third-person trigger sentence would lift the two weakest dimensions.

Suggestions

Add an explicit 'Use when...' trigger clause to cover the 'when' and unlock completeness, e.g. 'Use when you have an existing Obsidian vault and want to add the Claude PKM system without starting from the template.'

Rewrite in third person to avoid the voice penalty, e.g. 'Scaffolds the PKM system onto an existing Obsidian vault. Scans vault structure, maps folders interactively, and generates configuration — no template required.'

Include natural trigger-term variations users would actually say ('existing Obsidian vault', 'bring your own vault', 'adopt', 'BYOV') to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ('Scaffold', 'Scans', 'maps folders interactively', 'generates configuration') which would anchor at 3, but the second-person phrasing 'Scans your vault structure' triggers the voice penalty, reducing the score by 1.	2 / 3
Completeness	The 'what' is clearly stated (scaffold/scan/map/generate), but there is no 'Use when...' clause or equivalent explicit trigger guidance, so per the judging guidelines completeness is capped at 2.	2 / 3
Trigger Term Quality	Relevant natural terms are present ('existing Obsidian vault', 'PKM system', 'template'), but there is no explicit trigger clause and coverage of variations a user would say ('bring your own vault', 'adopt', 'BYOV') is thin, matching the 'some relevant keywords but missing common variations' anchor.	2 / 3
Distinctiveness Conflict Risk	The niche is clear and specific ('onto an existing Obsidian vault ... no template required'), distinguishing it from template-based onboarding, so it is unlikely to trigger for the wrong skill.	3 / 3
	Total	9 / 12 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: ballred/obsidian-claude-pkm
Path: vault-template/.claude/skills/adopt/SKILL.md
Commit: ef1e4da

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