Agent Instruction Authoring

Scope and loading

Keep durable project constraints in the host's standing file, such as AGENTS.md or CLAUDE.md, and task-specific workflows in skills. Keep repository-specific packaging rules and validation commands in repository instructions, not a portable skill. Check actual loading before removing duplicate safety or approval rules; a distributed skill cannot assume the user's global instructions.

The description is injected into the system prompt and may be shortened when the skill catalog is large. Write it in third person or imperative, never first or second person. Lead with the action and the situation, using words the user would say, so the shortened line still routes. Prefer Use when adding or changing a migration, or reviewing its rollout to Use when working with databases. Add a short exclusion only when a neighboring skill would claim the same request. Avoid keyword lists, overlapping triggers, and loading a portable skill before every edit or commit. A new skill needs a distinct, recurring trigger. Omit optional and host-only frontmatter unless every consumer parses those fields the same way.

Keep compact guidance in SKILL.md. Move detail into a reference only when it is substantial, independently useful, and unused on most activations; a short section stays inline. Link each reference with a forward-slash path directly from SKILL.md, one level deep. Add a contents list only when a partial read of that reference would miss later sections.

Keep house preferences, consequential traps, and ordering that matters. Leave routine choices open. State an exact command only when variation is a defect; otherwise state the outcome and the constraint. Use a checklist only for that fragile sequence. Run a script for a deterministic operation instead of pasting the script into the prompt, and add a script, tool, or reference only for that need. One past failure does not become a universal gate. Committed instructions steer other contributors' agents; keep them model-neutral, delete workarounds for a model no longer in use, and leave out vendor alignment notes and knowledge the model already has.

Authorization and clarification

• State that user instructions take precedence over skill guidelines, within higher-priority instructions and host permissions. A skill must not silently expand scope, replace the requested outcome, or imply permission for external actions.
• Requests for review or analysis alone are read-only; an explicit request to review and fix authorizes in-scope edits. Implementation requests authorize necessary in-scope code, tests, docs, configuration, and non-destructive validation.
• Make routine, reversible choices from available evidence. Ask when missing information materially changes the outcome, requirements conflict, or an explicit approval boundary applies. Explain the concrete decision and recommendation; group blocking questions and continue independent authorized work.
• Preserve authorization requirements for commits, pushes, releases, deployments, destructive actions, and unrelated changes. A requested action includes routine in-scope prerequisites. Reuse existing authorization; when approval is still needed, finish authorized preparation first so the user can review the concrete result.
• If an instruction causes a pause, confirmation request, incomplete work, or a change from the user's intent, name and link to the exact file, quote the relevant instruction, and explain its effect. Distinguish explicit requirements from interpretation; ordinary trade-offs and user-authorized scope changes are not new approval gates.