Agent Guide

Agent instructions are not where you prove how much you know. They are where you prevent the next predictable mistake.

Use this skill to help a person understand and shape their own Agent instruction system. The goal is not to produce one generic perfect AGENTS.md; the goal is to preserve the user's real workflow while making the always-loaded instructions thinner, safer, and easier for an Agent to follow.

Non-Negotiables

• Do not edit global user configuration directly unless the user explicitly asks for execution.
• For global Agent settings, first read the relevant file or pasted text, then propose a draft or diff.
• Before rewriting an existing instruction file, identify what the old file was trying to preserve and make sure the new version does not silently remove those capabilities.
• Do not assume the current working directory is the target project. Confirm the target when the task involves global or project instructions.
• Keep source attribution visible when the output is based on public articles, screenshots, copied text, or another person's framework.
• Do not copy long passages from source articles. Summarize, transform, and credit.
• Do not load or paste every reference into the final instruction file. Put details in skills, references, memory, hooks, CI, settings, or tools.

Mode Selection

Use Quick Audit when the user already has an instruction file and wants a review, comparison, diff, or lean rewrite.

Use Guided Rebuild when the user wants a personalized Agent setup and the target workflow, installed skills, memory habits, or preferred structure are unclear.

Quick Audit Workflow

1. Identify the target: global instructions, project instructions, rule files, memory, skill, hook, MCP, settings, article, or README.
2. Confirm whether the user wants an audit, draft, comparison, or actual file edit.
3. Read only the relevant current text. Avoid broad history scans unless the user asks.
4. Identify the original intent: what behaviors, routes, preferences, and safety boundaries the current file is trying to preserve.
5. Classify every meaningful rule into the buckets below.
6. Delete generic advice the model already knows.
7. Rewrite kept rules into short, concrete, action-oriented instructions.
8. Move long workflows into skills, templates, examples, or references.
9. Move enforceable behavior into hooks, settings, CI, permissions, or scripts when possible.
10. Run a regression check: list any old capability that is weakened, removed, or moved elsewhere.
11. Return a proposed version before mutating global or personal configuration.

Guided Rebuild Workflow

Use this when the user wants the Agent to fit their personal work style, not a generic template.

1. Inventory the current sources, only as needed:
• current global or project instruction file;
• installed skill names or available workflow tools;
• relevant memory/preferences if the user asks for personalization or prior context;
• project-specific instructions when the target is a project Agent file.
2. Ask only the missing questions that materially change the Agent design. Prefer 3-7 short questions:
• What work should this Agent optimize for: coding, planning, writing, research, demos, maintenance, or a mix?
• Should the Agent default to direct answers, plans, or execution?
• Which workflows require confirmation before file edits?
• Which installed skills does the user already know and want to call manually?
• Which skills should be routed automatically because the user forgets or does not want to remember names?
• What should stay in memory versus always-loaded instructions?
• What final report format is actually useful to the user?
3. Build a modular template. Include only blocks the user needs:
• Language And Tone;
• Operating Principles;
• Context Budget;
• Instruction Priority;
• Task Router;
• Skill And Tool Routing;
• Coding Discipline;
• Safety And Boundaries;
• Validation;
• Final Report;
• Optional Project Defaults.
4. Keep the final instruction file thin. Put repeatable workflows into skills, evolving preferences into memory, and enforceable behavior into hooks, CI, settings, or permissions.
5. Compare the proposal against the old file before recommending it.

Buckets

Keep In Always-Loaded Instructions

Use for rules that apply almost every time: default language or tone, permission and safety posture, lightweight mode for simple questions, user-specific collaboration preferences, and boundaries that would be dangerous to infer.

Keep In Project Instructions

Use for stable project facts the AI cannot safely infer: build, test, lint, and format commands; architecture boundaries; generated or no-touch paths; files that must change together; and domain vocabulary that affects correctness.

Move To Skills Or Rules

Use for repeatable workflows that only matter in certain tasks: debugging loops, TDD, frontend visual validation, PDF/document processing, deployment, article shaping, review checklists, and Agent instruction audits.

Move To Memory

Use for evolving preferences or lessons learned over time: user habits, project lessons, historical decisions, and recurring collaboration preferences. Do not use memory for secrets, hard requirements, or rules that must be enforced.

Move To Hooks, Settings, CI, Or Permissions

Use for behavior that should be enforced by the environment: block destructive commands, prevent committing secrets, run formatters or tests, enforce generated-file rules, or protect deployment settings.

Move To MCP, Plugins, Browser, Or Official Docs

Use for external systems and live capabilities: GitHub issues, PRs, review comments, CI; Vercel deployments, env vars, domains, logs; Figma files; browser validation; databases; official docs; current prices, laws, model names, and product behavior.

Move To README, Article, Examples, Or References

Use for human-facing explanation, teaching, examples, source notes, glossary, long tables, publishing notes, and background material.

Delete Or Rewrite

Delete generic advice such as "be careful", "use best practices", "write clean code", "think deeply", or "make it professional" unless it can be rewritten as a concrete trigger and action.

Rule Test

Ask these before keeping a rule always loaded:

1. Would the AI likely get this wrong without the rule?
2. Is it needed across many tasks or sessions?
3. Is it stable enough to keep loaded?
4. Does it tell the AI what to do, not just how to feel?

If not, delete it or move it.

Good Rule Pattern

Use:

When [specific situation], do [specific action], because [short reason or boundary].

Examples:

• For simple answers, do not read memory, skills, project files, or the web unless correctness requires it.
• Before editing global Agent settings, propose the exact diff and wait for confirmation.
• In this repo, do not touch generated files under dist/; regenerate them through the build command.
• If the task is a repeatable multi-step workflow, consider a skill instead of adding more global rules.

Output Formats

For an audit, return:

Keep
Move
Delete
Rewrite
Risks

For an old-vs-new comparison, return:

Original Intent
Improvements
Lost Or Weakened Capabilities
Safety Changes
Simplicity Changes
Recommendation

For a guided rebuild, return:

Questions
Assumptions
Modular Draft
Moved Elsewhere
Regression Check