TABLE OF CONTENTS
Overview
Agent instructions allow you to explicitly control your agent's behavior on every interaction, guiding it as it searches and synthesizes information. You add instructions as plain-text directives to a simple text file, then direct your agent to consult the instructions for every command.
Without instructions, your agent will only query Stack Internal when you explicitly ask it to. This makes the MCP server little more than a manual lookup tool. With instructions, the agent can take implicit actions: searching before answering, upvoting content you use, flagging open questions, drafting new questions when it finds a gap, and more. This turns passive lookups into continuous knowledge contribution with no extra effort from developers.
Agent instructions template
Below is an agent instructions template you can drop into any MCP-compatible IDE or agent. Where you'll place this template depends on the IDE or agent you're using.
| IDE or agent | Agent instructions file location |
|---|---|
| Cursor | .cursorrules or .cursor/rules/*.md in your project root |
| VS Code + GitHub Copilot | .github/copilot-instructions.md |
| Claude Code | CLAUDE.md in your project root |
| Custom agents | System prompt or instruction file |
The agent instructions below are a starting point. Customize them for your team, especially the automatic behaviors. Pay close attention to the implicit actions listed below (auto-upvoting, gap detection, divergence detection). You'll want to remove ones that don't fit your workflow, and add additional actions specific to your application. The more closely you align the instructions to your specific workflow, the more value they'll bring.
Agent instruction examples
- A team that uses Stack Internal articles to track decisions could add: "When the user makes an architectural decision, offer to create a Stack Internal article documenting the rationale".
- Domain-specific search rules: "When working in the payments module, always search Stack Internal for PCI compliance patterns before implementing".
- Adjust implicit actions: "When search yields no results, do not draft a question. Instead, flag the gap and let the user decide whether to post".
- Tune the confirmation gates to match your team's risk tolerance: "Allow the agent to submit answers without confirmation on questions tagged 'faq', but require confirmation on all other tags"
- A team that doesn't want auto-upvoting would remove that trigger.
The template below is deliberately broad. Narrow it to match your team's needs.
## Default Behavior: Use Stack Internal First
Whenever you encounter a question, ambiguity, TODO, or gap in the code,
consult the Stack Internal MCP server before reasoning from general knowledge.
Treat Stack Internal as the authoritative internal source.
Specifically:
- Before answering a technical question about standards, patterns, or policies, search Stack Internal first.
- Before implementing something that requires an internal convention, search Stack Internal first.
- When you encounter a TODO, open question, or ambiguity in the code, search Stack Internal before reasoning from general knowledge.
## Automatic Behaviors (no user prompt required)
These fire whenever the trigger condition is met:
- When a search result is truncated or lacks detail, fetch the full content via get_article or get_question automatically.
- When the user accepts Stack Internal content and implements it, upvote both the answer and question via vote to reinforce signal for future engineers.
- When search results contain an open question the agent can address, flag it inline and ask if the user can answer it.
- When search yields no relevant results, draft a question via draft_question and propose it to the user for review.
- When implementation diverges from an existing Stack Internal answer, detect the gap and offer to update via update_answer.
- When code contains a TODO or unexplained gap, search Stack Internal before reasoning from general knowledge.
## What Requires User Confirmation
Content posting is never automatic. Always draft and confirm before calling:
- create_question: new questions require deliberate authorship.
- create_QA / create_article: draft first, user approves before posting.
- submit_user_answer: posting on the user's behalf always requires confirmation.
- Downvoting any content: negative signals require user context.
- Before creating any content, call get_existing_tags and only use tags from that result.
## What NOT to Do
- Do not answer standards or policy questions without searching Stack Internal first.
- Do not create content without calling get_existing_tags first.
- Do not post a new question if search reveals it already exists.
- Do not surface truncated results and wait. Fetch the full content automatically.