create-instructions

Create an instructions file (.instructions.md) for a project rule or convention.

Quality

64%

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 ./extensions/copilot/assets/prompts/skills/create-instructions/SKILL.md

Quality

Content

75%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 compact, well-structured procedural skill with concrete extraction/clarification/iteration guidance and a clear sequence. Its main gap is reliance on an externally referenced template file (instructions.md) that is not part of the bundle, which slightly limits actionability and verifiable navigation.

Suggestions

Either include the 'instructions.md' template as a bundled reference file or inline a minimal template/structure so the deliverable format is actionable without an external dependency.

Add an explicit validation checkpoint in the Iterate loop (e.g., 're-read the saved instruction and confirm it is unambiguous and enforceable before finalizing').

Drop the redundant 'Guide the user to create an instructions file.' line and the closing 'Remember to follow agent-customization' sentence to tighten token efficiency.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence with no padding or explanation of known concepts; only minor redundancies ('Guide the user to create an instructions file.' echoing the description, and a repeated agent-customization reminder) keep it just below the 'every token earns its place' level.	4 / 5
Actionability	It gives concrete, executable guidance for an instruction-only skill (three specific extraction targets, three specific clarifying questions, three iteration steps), with the only gap being the output template deferred to the referenced 'instructions.md' rather than shown inline.	4 / 5
Workflow Clarity	The process is clearly sequenced (Extract -> Clarify -> Iterate) with a soft feedback checkpoint ('identify the most ambiguous or weak parts and ask about those'); since this is a non-destructive, non-batch skill the destructive-validation cap does not apply, but the checkpoint is implicit rather than an explicit validate/fix/retry loop.	4 / 5
Progressive Disclosure	The skill is under 50 lines with clean section headers and one-level-deep, clearly signaled references ('instructions.md', 'agent-customization'), so it is well-organized; it sits just below 5 because the referenced 'instructions.md' template is not present in the bundle to verify navigation.	4 / 5
	Total	16 / 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 states what the skill produces and pins a concrete file type, but it omits any explicit trigger/usage guidance and offers only one action, leaving completeness and specificity at mid-range. Distinctiveness is reasonably strong thanks to the .instructions.md reference.

Suggestions

Add an explicit 'Use when...' clause naming natural triggers (e.g., 'Use when the user wants to codify a recurring correction, style rule, or project convention into a persistent instruction').

List 1-2 more concrete actions (e.g., 'extract from conversation history, draft, and save') to lift specificity toward comprehensive coverage.

Add common synonym triggers (e.g., 'guidelines', 'standards', 'coding rules') to broaden natural keyword coverage.

Dimension	Reasoning	Score
Specificity	It names the domain ('project rule or convention') and one concrete action ('Create an instructions file (.instructions.md)') but lists only a single action rather than several, fitting the 'names domain and 1-2 concrete actions' anchor rather than the 'several specific actions' level above.	3 / 5
Completeness	It clearly answers 'what' (create an instructions file for a project rule/convention) but provides no explicit 'when' / 'Use when...' guidance, which the rubric caps at 3.	3 / 5
Trigger Term Quality	It includes relevant keywords ('instructions file', '.instructions.md', 'project rule', 'convention') but lacks common variations or a natural 'Use when...' trigger phrase, so it sits at 'some relevant keywords but missing common variations' rather than the fuller coverage anchor.	3 / 5
Distinctiveness Conflict Risk	The specific '.instructions.md' file type and 'rule or convention' scope give it a fairly distinct niche with only minor overlap risk against the related 'agent-customization' skill, fitting 'mostly distinct; minor overlap risk' rather than the broader level below.	4 / 5
	Total	13 / 20 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: posit-dev/positron
Path: extensions/copilot/assets/prompts/skills/create-instructions/SKILL.md
Commit: 9bb0f27

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