using-agent-skills

Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

92%

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-engineered overview: concise, actionable, and clearly sequenced with a discovery flowchart and lifecycle that genuinely guide behavior. The one real weakness is progressive disclosure — it references a non-existent references/ file rather than shipping the bundle.

Suggestions

Create references/definition-of-done.md (the file the body cites) so the one-level-deep reference resolves to real content.

Consider splitting the full skill catalog (the Quick Reference table) into a references/skill-catalog.md file so SKILL.md stays a lean routing overview.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence: the discovery flowchart, lifecycle sequence, and quick-reference table each earn their tokens without restating concepts Claude already knows, matching the 'every token earns its place' anchor.	3 / 3
Actionability	Concrete executable guidance is pervasive — the ASCII flowchart maps task shapes to named skills, the numbered lifecycle sequence lists exact skill chains, and behaviors like the ASSUMPTIONS template give copy-ready direction.	3 / 3
Workflow Clarity	Multi-step processes are explicitly sequenced with checkpoints: the discovery flowchart branches by phase, the lifecycle sequence is numbered with a parallel-instrumentation note, and 'Verify, Don't Assume' defines an explicit evidence gate.	3 / 3
Progressive Disclosure	Sections are well-organized and the body points one level deep to references/definition-of-done.md, but that references/ directory does not exist, so the signaling is not backed by an actual bundle — capping below the level-3 cleanly-split structure.	2 / 3
	Total	11 / 12 Passed

Description

67%

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 answers both what and when with an explicit Use-when clause, but its trigger terms are more meta-jargon than natural user phrasing and its capabilities are only partially enumerated. It is solid but not exemplary.

Suggestions

Add concrete natural trigger phrases users would actually say (e.g., 'when you're unsure which skill fits', 'picking the right workflow skill') instead of relying on 'starting a session'.

List the specific actions the skill performs beyond 'discovers and invokes' (e.g., 'matches the task's development phase to a skill and lists the skill sequence') to raise specificity.

Dimension	Reasoning	Score
Specificity	"Discovers and invokes agent skills" names the domain and two actions but stops short of listing multiple concrete capabilities, matching the 'names domain and some actions' anchor rather than the comprehensive level-3 list.	2 / 3
Completeness	It explicitly answers both 'what' ("Discovers and invokes agent skills") and 'when' (an explicit "Use when..." clause), satisfying the level-3 anchor for both halves.	3 / 3
Trigger Term Quality	Triggers like "starting a session" and "discover which skill applies to the current task" are relevant but lean on internal/meta jargon and omit common natural variations, so coverage is partial rather than level-3 breadth.	2 / 3
Distinctiveness Conflict Risk	The "meta-skill that governs how all other skills are discovered and invoked" carves a niche, but its trigger of discovering 'which skill applies' is broad enough to overlap with many skills, so it is not a clearly conflict-free level 3.	2 / 3
	Total	9 / 12 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: addyosmani/agent-skills
Commit: 70b7506

Reviewed: 3 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.