How to Add AI Agents in Cursor and VS Code (Step-by-Step)

Why Loading an Agent Correctly Matters

Downloading an agent from AgentHut is just the first step. How you load it into your editor determines whether it works consistently every time, only in specific projects, or disappears the moment you close a tab.

This guide covers every method — from the fastest one-shot paste to persistent workspace-level configuration — so you can choose the right approach for your workflow.

---

What You're Working With

Every agent on AgentHut is a .md file containing structured instructions. When you load it into Cursor or VS Code + Copilot, the AI reads it as system-level context before answering any of your questions.

The file typically follows this structure:

# Agent Name

> One-line description of what this agent does.

## Role
You are [specific persona with expertise]...

## Capabilities
- What the agent can do

## Instructions
Step-by-step behavior rules...

## Output Format
How responses should be structured...

## Constraints
What the agent should never do...

You don't need to modify this file to use it — just load it using one of the methods below.

---

Loading Agents in Cursor

Cursor has three places where you can load agent instructions, each with different scope.

Method 1: .cursorrules — Project-Level (Recommended)

The .cursorrules file is Cursor's primary mechanism for project-scoped AI behavior. It lives in your project root and is automatically read by Cursor's AI at the start of every conversation in that project.

Steps:

1. Download your agent .md file from AgentHut
2. In your project root, create (or open) .cursorrules
3. Copy the full content of the agent .md file and paste it into .cursorrules
4. Save the file — no restart required
5. Open a new Cursor Chat (Ctrl+L / Cmd+L) — the agent is now active

# Your project structure
my-project/
├── .cursorrules          ← paste agent content here
├── src/
├── package.json
└── ...

Pro tip: Commit .cursorrules to your git repository. Every team member who opens the project in Cursor automatically gets the same agent — no manual setup required.

---

Method 2: Cursor Settings → Rules for AI — User-Level

User-level rules apply across all your projects in Cursor — useful for agents you want active everywhere, like a code review or documentation agent.

Steps:

1. Open Cursor Settings: Cmd+, (macOS) or Ctrl+, (Windows/Linux)
2. Navigate to Features → Rules for AI
3. Paste the agent content into the text area
4. Close settings — the rule is active immediately in all new chats

Setting	Scope	Persists
.cursorrules file	Current project only	Yes — in git
Rules for AI (settings)	All projects	Yes — in Cursor config
In-chat paste	Current conversation only	No

---

Method 3: Paste Directly into Cursor Chat — One-Shot

The fastest method for a one-time use. No files needed.

Steps:

1. Open Cursor Chat (Ctrl+L / Cmd+L)
2. Open your downloaded agent .md file in any text editor
3. Copy all content (Ctrl+A → Ctrl+C)
4. Paste at the start of your chat message, then add your actual question on a new line
5. Send — Cursor's AI reads the agent as context for this conversation

This works well for quick experiments before committing an agent to .cursorrules.

---

Method 4: @-mention a File in Cursor Chat

If you keep the agent .md file in your project, you can reference it directly in chat using Cursor's file mention syntax.

Steps:

1. Save the agent .md file anywhere in your project (e.g., agents/code-reviewer.md)
2. Open Cursor Chat
3. Type @code-reviewer.md (or the file name) — Cursor autocompletes
4. Select the file from the dropdown
5. Add your question — Cursor includes the full file as context

@code-reviewer.md Review the selected function for performance issues.

This is ideal when you have multiple agents in a project and want to choose which one to activate per conversation.

---

Method 5: Cursor Composer — Multi-File Workflows

For agents that operate across multiple files (like a code migration agent or a test generator), use Cursor's Composer mode.

Steps:

1. Open Composer: Cmd+I (macOS) or Ctrl+I (Windows/Linux)
2. At the top of the composer, type @ and select your agent file
3. Add the files you want the agent to work on using additional @file mentions
4. Describe your task — the agent's instructions plus all selected files become the working context

---

Loading Agents in VS Code with GitHub Copilot

VS Code doesn't have a .cursorrules equivalent built in, but GitHub Copilot supports persistent instructions through workspace files and the Copilot Chat settings.

Method 1: .github/copilot-instructions.md — Workspace Level (Recommended)

GitHub Copilot automatically reads this file when it exists in your repository and applies it as workspace-scoped context for all Copilot Chat interactions in that project.

Steps:

1. Create the folder .github/ in your project root (if it doesn't exist)
2. Create the file .github/copilot-instructions.md
3. Paste the full content of your AgentHut agent .md file into it
4. Save — Copilot Chat picks it up immediately for new conversations

my-project/
├── .github/
│   └── copilot-instructions.md    ← paste agent content here
├── src/
└── package.json

Note: This file is supported in VS Code with the GitHub Copilot extension v1.160+. Ensure your Copilot extension is up to date.

---

Method 2: Copilot Chat Custom Instructions — User Level

For instructions you want active in every workspace (not project-specific):

Steps:

1. Open VS Code Settings: Cmd+, (macOS) or Ctrl+, (Windows/Linux)
2. Search for "copilot instructions"
3. Find GitHub Copilot: Chat › Instructions setting
4. Click Edit in settings.json
5. Add your agent content as a string value:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "You are a senior TypeScript engineer reviewing code for correctness, performance, and maintainability. Focus on type safety and avoid any types. Always suggest tests for new functions."
    }
  ]
}

For longer agents, reference the file instead of inlining:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "file": ".github/copilot-instructions.md"
    }
  ]
}

---

Method 3: Paste Directly into Copilot Chat — One-Shot

For a quick, one-conversation load:

1. Open Copilot Chat (Ctrl+Alt+I or click the Copilot icon in the sidebar)
2. Copy your agent .md file content
3. Paste it as the first message, then follow with your question
4. Send — Copilot treats the pasted content as conversation context

---

Method 4: Attach the Agent File in Copilot Chat

Newer versions of VS Code Copilot support attaching files directly to a chat:

1. Open Copilot Chat
2. Click the Attach context paperclip icon (bottom of chat input)
3. Select your agent .md file from your project
4. Ask your question — Copilot reads the full file as context

---

Side-by-Side Comparison

Method	Tool	Scope	Persists	Best For
.cursorrules	Cursor	Project	Yes (git)	Team-shared project agents
Rules for AI (settings)	Cursor	All projects	Yes	Personal agents active everywhere
@-file mention	Cursor	Per conversation	No	Switching agents per task
Composer + @	Cursor	Per session	No	Multi-file agent workflows
.github/copilot-instructions.md	VS Code	Project	Yes (git)	Team-shared project agents
settings.json instructions	VS Code	All workspaces	Yes	Personal always-on instructions
Chat paste	Both	Per conversation	No	Quick one-off use

---

Tips for Getting the Most Out of Your Agents

Stack agents, don't replace them. You can combine a project-level agent (in .cursorrules or .github/copilot-instructions.md) with a conversation-level @-file mention. The AI reads both — use the project file for baseline standards and the @-file for task-specific instructions.

Keep your agent file in the repo. Even if you paste it into settings, keep the source .md in a /agents folder. This makes it easy to update, version-control, and share.

Use specific agents for specific files. In Cursor, you can @-mention a Python testing agent only when working on test files, and a documentation agent only in /docs. No need to activate every agent for every task.

Check for context window limits. Very long agent files (>4,000 words) can consume a significant portion of the model's context window. Trim anything that isn't load-bearing — constraints and output formats are more important than lengthy examples.

Test your agent immediately. After loading, ask the AI "What are your instructions?" or "What role are you playing?" A well-loaded agent will summarize its role accurately.

---

Quick Reference: Keyboard Shortcuts

Action	Cursor	VS Code + Copilot
Open AI Chat	Ctrl+L / Cmd+L	Ctrl+Alt+I
Open Composer	Ctrl+I / Cmd+I	—
@-mention file	Type @ in chat	Type # in chat
Open Settings	Ctrl+, / Cmd+,	Ctrl+, / Cmd+,
Command Palette	Ctrl+Shift+P	Ctrl+Shift+P

---

What to Do If the Agent Isn't Being Applied

If the AI seems to be ignoring your agent, try these checks:

1. Start a new chat. Open a fresh conversation — pasted context from a previous session doesn't carry over.
2. Check the file is saved. Unsaved .cursorrules or .github/copilot-instructions.md won't be read.
3. Reload the window. Ctrl+Shift+P → "Developer: Reload Window" forces VS Code to re-read settings and workspace files.
4. Verify file location. .cursorrules must be in the project root, not a subfolder. copilot-instructions.md must be in .github/, not in the project root.
5. Test with a direct ask. Send "What are your current instructions?" to verify the agent is active.

---

Ready to find the right agent for your stack? Browse the AgentHut marketplace →