writing-agent-instructions

How to write great agent instructions for an agent-native app or template: AGENTS.md, skills, and tool/action descriptions. Use when authoring or reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or deciding what belongs in instructions vs skills vs memory.

Quality

81%

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

Quality

Content

78%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.

A highly actionable, well-structured meta-guide that earns its length with concrete commands, templates, and APIs. Its main weakness is practicing what it preaches: it advocates a lean SKILL.md with depth in references/, but ships as a long single file with no reference files.

Suggestions

Split long detail into reference files (e.g. references/secrets-hygiene.md, references/action-descriptions.md, references/agents-template.md) and link to them from the body, following the progressive-disclosure pattern the skill itself prescribes.

Tighten the discursive rationale passages ("Say each thing once", "Prefer judgment over rules") to imperative rules to reduce token cost without losing the guidance.

Add an explicit end-to-end "authoring a new skill/instructions" workflow with ordered steps and a final sync→guard validation checkpoint to raise workflow clarity.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and information-dense for a meta-guide, with specific commands and APIs rather than basic-concept padding, but a few discursive passages (e.g. "Repetition is not reinforcement — it is three chances to disagree") could be trimmed, fitting the 4 anchor rather than the fully lean 5.	4 / 5
Actionability	Provides concrete, copy-paste-ready guidance — specific commands (pnpm sync:workspace-skills, pnpm guard:workspace-skills), the 6,000/~5,500 char cap, a full AGENTS.md template, frontmatter examples, and named APIs (defineAction, useActionQuery, tool-search, sendToAgentChat({ openSidebar: true })) covering the common cases, matching the 5 anchor.	5 / 5
Workflow Clarity	Multi-step processes are sequenced with checkpoints ("run pnpm sync:workspace-skills after editing... and pnpm guard:workspace-skills before calling the guidance done"; the verify-before-done read-back loop), but it is a principles collection rather than one end-to-end workflow, so minor gaps keep it at 4 rather than 5.	4 / 5
Progressive Disclosure	Section structure and cross-skill links (Related Skills: create-skill, actions, context-awareness) are clear, but the file is a ~360-line monolith for its breadth with no references/ bundle files shipping, inlining depth that the skill itself tells authors to push into references/, matching the 3 anchor ("content that should be separate is inline").	3 / 5
	Total	16 / 20 Passed

Description

83%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.

A strong description: it states a concrete capability and an explicit, multi-trigger "Use when" clause for a well-scoped niche. Minor improvements are possible in trigger synonym coverage and disambiguating the SKILL.md trigger from a create-skill skill.

Suggestions

Add a distinguishing qualifier to the "writing a SKILL.md" trigger (e.g. "writing or structuring a SKILL.md's frontmatter and layering") to reduce overlap with a create-skill skill.

Add one or two plain-language synonyms (e.g. "agent prompts", "tool descriptions") so the trigger fires on more natural user phrasings.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete authoring actions — "authoring or reviewing AGENTS.md", "writing a SKILL.md", "wording action descriptions", "deciding what belongs in instructions vs skills vs memory" — with only minor coverage gaps, fitting the 4 anchor rather than the fully comprehensive 5.	4 / 5
Completeness	Explicitly answers both what ("How to write great agent instructions... AGENTS.md, skills, and tool/action descriptions") and when ("Use when authoring or reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or deciding what belongs...") with concrete trigger phrases, matching the 5 anchor.	5 / 5
Trigger Term Quality	Includes natural terms a developer of agent-native apps would actually say ("AGENTS.md", "SKILL.md", "skills", "action descriptions", "instructions", "memory") with good synonym coverage; a few natural phrasings may be missing, so it sits at 4 rather than 5.	4 / 5
Distinctiveness Conflict Risk	The "agent-native app or template" framing and instruction-allocation triggers carve a clear niche, but "writing a SKILL.md" directly overlaps a sibling create-skill skill, giving minor overlap risk consistent with the 4 anchor rather than the minimal-conflict 5.	4 / 5
	Total	17 / 20 Passed

Validation

81%

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

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	13 / 16 Passed

Repository: BuilderIO/agent-native
Path: .agents/skills/writing-agent-instructions/SKILL.md
Commit: a06e0ac

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