orient

Generates a repo-specific orientation.md resource for the learning-opportunities skill. Invoke directly when the user asks for repo orientation; do not trigger automatically.

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./orient/skills/orient/SKILL.md

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 skill body is highly actionable with concrete commands, a precise output template, and a clearly sequenced two-path workflow including validation in the showboat path. It is slightly held back by inline academic citations that could be delegated and a dangling bibliography reference with no accompanying bundle file.

Suggestions

Move the inline academic source citations (Steps 3a-3f) entirely into resources/orient-bibliography.md to tighten conciseness.

Add an explicit verification step to the default path (e.g. re-read the written orientation.md and confirm every required section is non-empty).

Ship the referenced resources/orient-bibliography.md in a references/ bundle so the in-body link resolves to a real file.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean instructional content with copy-paste commands and avoids explaining concepts Claude already knows; minor trims are possible (inline academic source citations in Steps 3a-3f could live solely in the bibliography file), fitting the 'efficient; minor instances of over-explanation' anchor.	4 / 5
Actionability	Guidance is fully executable: concrete commands ('find . -maxdepth 3 ...', 'git log --oneline -20', 'uvx showboat init <path> "<Title>"'), a per-language manifest file table, and an exact output template, matching the 'fully executable; copy-paste ready' anchor.	5 / 5
Workflow Clarity	Both paths are clearly sequenced (Step 1-5 and Showboat Step 1-5) with checkpoints (uv presence check that stops on failure, 'uvx showboat verify' with a fix-and-retry loop); not 5 because the default path lacks an explicit verification of the generated orientation.md, leaving a minor validation gap.	4 / 5
Progressive Disclosure	Content is well-organized into clear sections with a single well-signaled one-level-deep reference (the bibliography maintainer note), matching the 'good structure; references mostly clear' anchor; not 5 because the referenced resources/orient-bibliography.md is not present in any bundle directory.	4 / 5
	Total	17 / 20 Passed

Description

66%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 states both what it does and when to invoke it, with strong distinctiveness from a specific niche and an explicit non-auto-trigger guard. It is slightly limited by a single concrete action and a single trigger phrase with no synonyms.

Suggestions

Add 1-2 more concrete actions (e.g. 'synthesizes key files and concepts, suggests orientation exercises') to raise specificity.

Broaden trigger coverage with natural synonyms like 'repo onboarding' or 'getting familiar with a codebase'.

Dimension	Reasoning	Score
Specificity	Names the domain ('repo-specific orientation.md resource') and one concrete action ('Generates'), matching the 'names domain and 1-2 concrete actions' anchor; not 4 because only a single action is described rather than several.	3 / 5
Completeness	Both 'what' (generates an orientation.md resource) and 'when' (invoke when the user asks for repo orientation; do not trigger automatically) are present and concrete, fitting the 'has both what and when; when could be more explicit' anchor; not 5 because only a single trigger phrase is given rather than multiple concrete triggers.	4 / 5
Trigger Term Quality	The phrase 'when the user asks for repo orientation' supplies a relevant natural keyword, but coverage is thin with no synonyms (e.g. onboarding, code walkthrough, getting familiar), matching the 'some relevant keywords but missing common variations' anchor.	3 / 5
Distinctiveness Conflict Risk	It targets a clear niche (repo orientation as a sub-resource for the named learning-opportunities skill) with an explicit 'do not trigger automatically' guard, giving minimal conflict risk and matching the 'clear niche with distinct triggers' anchor.	5 / 5
	Total	15 / 20 Passed

Validation

75%

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 — 12 / 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
relative_links	Relative link issues: 1 missing	Warning
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	12 / 16 Passed

Repository: DrCatHicks/learning-opportunities
Path: orient/skills/orient/SKILL.md
Commit: 3862d2e

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