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

84%

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

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.

A high-quality instruction-only skill body: concrete, example-backed, and full of non-obvious repo-specific constraints Claude cannot infer. Its weaknesses are modest — some sections could be tightened, and the guide preaches progressive disclosure while keeping all of its own depth inline in SKILL.md with no references/ bundle.

Suggestions

Split the secrets-hygiene and version-history pattern sections into a references/ file (e.g. references/secrets-hygiene.md) and keep only the invariant rule plus a pointer in SKILL.md, practicing the progressive disclosure the guide itself teaches.

Trim the 'Keep generated guidance in sync' and 'Bake in secrets hygiene' sections to their core rules; the detail lists of credential channels and sync commands push conciseness below lean.

Add an explicit authoring workflow with a validation loop (edit → run pnpm guard:workspace-skills and guard:agent-chat-context → fix → re-run before calling it done) so the verification steps scattered across sections form one clear checklist.

Dimension	Reasoning	Score
Conciseness	Dense and opinionated with no padding on concepts Claude already knows; every section carries repo-specific facts ("hard-sliced at COMPACT_PROMPT_RESOURCE_MAX_CHARS (6,000)", ".prettierignore", "scope: dev" semantics, guard commands). Not 5 because sections like "Keep generated guidance in sync" and "Bake in secrets hygiene" run longer than the rule they deliver and could be tightened.	4 / 5
Actionability	Fully concrete, copy-paste-ready guidance: exact commands ("pnpm guard:agent-chat-context", "pnpm sync:workspace-skills", "pnpm guard:workspace-skills"), complete templates (the AGENTS.md example, SKILL.md frontmatter examples, the defineAction snippet), a layer-ownership table, and explicit Do/Don't lists covering the common authoring cases. Instruction-only, but every rule comes with a literal example.	5 / 5
Workflow Clarity	As an authoring guide rather than a fragile multi-step process, sections sequence logically (surfaces → sync rules → request budget → layering → frontmatter → disclosure → tables → descriptions → honesty/secrets → Do/Don't) and validation checkpoints are built in ("run `pnpm guard:workspace-skills` before calling the guidance done"; the 6,000-char guard "fails the build"). Not 5 because there is no explicit fix-and-retry loop for the authoring workflow itself.	4 / 5
Progressive Disclosure	Well-sectioned body with clearly signaled one-level-deep pointers out to related skills (create-skill, actions, context-awareness, capture-learnings) rather than nested chains. Not 5 because the bundle has no references/ files and all ~360 lines are inline — sections like secrets hygiene or the version-history pattern could be pushed to references/; not 3 because structure and signaling are good and no content is clearly mis-placed.	4 / 5
	Total	17 / 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: third-person, concise, names concrete surfaces and actions, and carries an explicit multi-trigger "Use when…" clause. It would fire reliably on AGENTS.md/SKILL.md authoring requests. The only gaps are missing synonyms (e.g. CLAUDE.md, system prompt) that would broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists several specific surfaces ("AGENTS.md, skills, and tool/action descriptions") and concrete actions ("authoring or reviewing AGENTS.md", "writing a SKILL.md", "wording action descriptions", "deciding what belongs in instructions vs skills vs memory"). Not 5 because it names the deliverables but does not enumerate the concrete sub-tasks within each surface; well above the 1-2-action level of anchor 3.	4 / 5
Completeness	Explicitly answers both questions: "How to write great agent instructions for an agent-native app or template: AGENTS.md, skills, and tool/action descriptions" (what) and "Use when authoring or reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or deciding what belongs in instructions vs skills vs memory" (when, with concrete trigger phrases). Matches the anchor-5 example pattern exactly.	5 / 5
Trigger Term Quality	Good natural keyword coverage users would actually say: "AGENTS.md", "SKILL.md", "action descriptions", "instructions vs skills vs memory". Not 5 because common synonyms such as "CLAUDE.md", "system prompt", or "tool descriptions" as standalone triggers are absent; clearly above the 3 anchor, which requires missing common variations.	4 / 5
Distinctiveness Conflict Risk	Clear niche (authoring/reviewing agent instructions for agent-native apps and templates) with distinct trigger terms. Not 5 because closely related skills such as a generic create-skill or documentation-writing skill could compete for the same "writing a SKILL.md" trigger; far more specific than the broad anchor-2 examples.	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: a941a2e

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