Skip to content

Latest commit

 

History

History
527 lines (395 loc) · 11.4 KB

USER_GUIDE.md

File metadata and controls

527 lines (395 loc) · 11.4 KB

Complete User Guide: Using Your Chatmode Agents in VS Code

This guide will help you set up and use your custom AI agents across all your projects in VS Code.

Table of Contents

  1. Quick Start
  2. Setting Up Agents in Projects
  3. Using Agents in VS Code
  4. Managing Your Agents
  5. Troubleshooting
  6. Reference

Quick Start

For New Projects

When you create a new Git repository, agents are automatically included:

mkdir my-new-project
cd my-new-project
git init

✅ Done! Your agents are automatically linked via the Git template.

For Existing Projects

Navigate to your project and run:

cd /path/to/existing/project
setup-agents

✅ Done! Your agents are now available in this project.

Setting Up Agents in Projects

Method 1: Using the setup-agents Function (Recommended)

Step 1: Open a terminal and navigate to your project:

cd /path/to/your/project

Step 2: Run the setup command:

setup-agents

What happens:

  • Creates .github directory if it doesn't exist
  • Creates symlinks to your global agents in ~/chatmodes/
  • Links are created in both .github/agents/ and .github/chatmodes/ for compatibility

Output:

✅ Agents linked to ./github/agents
✅ Chatmodes linked to ./.github/chatmodes

Method 2: Using the Quick Alias

Step 1: Navigate to your project:

cd /path/to/your/project

Step 2: Run the alias:

link-agents

Output:

✅ Agents linked!

Method 3: Using the Standalone Script

Step 1: Run the script from anywhere:

~/setup-agents.sh /path/to/your/project

Or from within the project:

cd /path/to/your/project
~/setup-agents.sh

Verification

After setup, verify the agents are linked:

# Check the symlinks
ls -la .github/

# You should see:
# agents -> /home/krishnan/chatmodes
# chatmodes -> /home/krishnan/chatmodes

# List available agents
ls .github/agents/

Using Agents in VS Code

Step 1: Open Your Project in VS Code

code /path/to/your/project

Or open VS Code and use File → Open Folder

Step 2: Access GitHub Copilot Chat (or Your AI Extension)

If using GitHub Copilot:

  1. Press Ctrl+Shift+I (or Cmd+Shift+I on Mac) to open Copilot Chat
  2. Or click the chat icon in the activity bar

Step 3: Select an Agent

In the chat input box:

  • Type @ to see available agents
  • Or type @agent-name directly

Available agents include:

  • @python-coding-agent - Python development with PEP8
  • @java-coding-agent - Java with OOP and design patterns
  • @typescript-coding-agent - TypeScript with type safety
  • @javascript-coding-agent - Modern JavaScript ES6+
  • @react-coding-agent - React components and hooks
  • @nodejs-coding-agent - Node.js backend development
  • @rust-coding-agent - Rust with safety and performance
  • @go-coding-agent - Go with concurrency
  • @cpp-coding-agent - Modern C++ standards
  • @aws-cloud-agent - AWS infrastructure and IaC
  • @azure-cloud-agent - Azure solutions and deployments
  • @gcp-cloud-agent - Google Cloud Platform
  • @sql-coding-agent - SQL optimization
  • @postgresql-coding-agent - PostgreSQL features
  • @mongodb-coding-agent - MongoDB schema design
  • @code-review - Senior developer code reviews
  • @debugging-assistant - Systematic debugging help
  • @test-generator - Comprehensive test generation
  • @security-review - Security vulnerability analysis
  • @documentation-writer - Code documentation
  • @api-design-advisor - REST API design
  • @learning-explainer - Teaching and explanations
  • @staff-engineer - Technical leadership
  • And many more!

Step 4: Interact with the Agent

Example 1: Python Code Review

@python-coding-agent Review this function for PEP8 compliance and suggest improvements:

def calculate(x,y):
    result=x+y
    return result

Example 2: Debug a Problem

@debugging-assistant I'm getting a "TypeError: Cannot read property 'name' of undefined" 
in my React component. Here's the code:
[paste your code]

Example 3: Generate Tests

@test-generator Create comprehensive unit tests for this function:
[paste your function]

Step 5: Follow Agent Guidance

Each agent provides:

  • Detailed analysis based on their expertise
  • Code examples and suggestions
  • Best practices specific to their domain
  • Step-by-step instructions when needed

Managing Your Agents

Updating Agent Prompts

All agents are stored in: ~/chatmodes/

To update an agent:

Step 1: Edit the agent file:

code ~/chatmodes/python-coding-agent.chatmode.md

Step 2: Modify the prompt section:

prompt: |
  Your updated instructions here...

Step 3: Save the file

✅ All projects automatically get the update because they use symlinks!

Adding New Agents

Step 1: Create a new file in ~/chatmodes/:

cd ~/chatmodes
code my-new-agent.chatmode.md

Step 2: Use this template:

name: my-new-agent
description: Brief description of what this agent does
prompt: |
  You are an expert in [domain]. 
  
  [Detailed instructions for the agent...]
  
  [Best practices...]
  
  [Guidelines...]
settings:
  temperature: 0.2
  max_tokens: 512

Step 3: Save the file

✅ The new agent is immediately available in all projects!

Removing Agents

Simply delete or rename the agent file:

rm ~/chatmodes/unwanted-agent.chatmode.md
# Or rename it to disable
mv ~/chatmodes/old-agent.chatmode.md ~/chatmodes/old-agent.chatmode.md.disabled

Viewing All Available Agents

ls ~/chatmodes/*.chatmode.md

Or with descriptions:

grep -H "description:" ~/chatmodes/*.chatmode.md

Troubleshooting

Problem: Agents Don't Show Up in VS Code

Solution 1: Restart VS Code

# Close VS Code completely and reopen
code /path/to/your/project

Solution 2: Verify symlinks exist

cd /path/to/your/project
ls -la .github/

# Should show:
# agents -> /home/krishnan/chatmodes
# chatmodes -> /home/krishnan/chatmodes

Solution 3: Re-run setup

rm -rf .github/agents .github/chatmodes
setup-agents

Solution 4: Check GitHub Copilot extension

  • Ensure GitHub Copilot is installed and enabled
  • Check you're logged into GitHub
  • Verify Copilot has access to custom agents

Problem: Function setup-agents Not Found

Solution: Reload your bash configuration

source ~/.bashrc

Or open a new terminal window.

Problem: Agents Work in One Project But Not Another

Solution: Each project needs its own setup

cd /path/to/other/project
setup-agents

Problem: Changes to Agent Not Appearing

Solution 1: Verify you're editing the right file

# Check where the symlink points
readlink -f .github/agents

# Should show: /home/krishnan/chatmodes

Solution 2: Restart VS Code after making changes

Solution 3: Clear VS Code cache (rare)

rm -rf ~/.config/Code/Cache/*

Problem: Permission Denied

Solution: Check file permissions

chmod 644 ~/chatmodes/*.chatmode.md
chmod 755 ~/chatmodes

Reference

Command Reference

# Setup agents in current directory
setup-agents

# Setup agents in specific directory
setup-agents /path/to/project

# Quick link in current directory
link-agents

# Standalone script
~/setup-agents.sh

# List all agents
ls ~/chatmodes/*.chatmode.md

# Search for specific agent
ls ~/chatmodes/ | grep python

# View agent configuration
cat ~/chatmodes/python-coding-agent.chatmode.md

File Locations

Item Location
Agent Files ~/chatmodes/*.chatmode.md
Setup Script ~/setup-agents.sh
Bash Functions ~/.bashrc (at the end)
Git Template ~/.git-templates/.github/
Project Agents .github/agents/ (symlink)
Project Chatmodes .github/chatmodes/ (symlink)

Agent File Structure

name: agent-name                    # Unique identifier (no spaces)
description: One-line description   # Brief description
prompt: |                           # Multi-line prompt
  Main instructions...
  
  **Section:**
  - Details
  - More details
  
  Best practices...
settings:
  temperature: 0.2                  # 0.0-1.0 (lower = more focused)
  max_tokens: 512                   # Max response length

Best Practices

Agent Naming:

  • Use lowercase with hyphens: python-coding-agent
  • Be descriptive but concise
  • Use consistent naming pattern

Prompt Writing:

  • Start with clear role definition
  • Organize with headers (**, ##, etc.)
  • Include specific guidelines and examples
  • Specify expected output format
  • Add edge cases and constraints

Temperature Settings:

  • 0.2 - Focused, deterministic (code, reviews)
  • 0.3 - Balanced (debugging, explanations)
  • 0.4 - Creative (brainstorming, ideation)
  • 0.5+ - More creative (rarely needed)

Additional Resources

  • Main README: ~/chatmodes/README.md
  • Global Setup Guide: ~/chatmodes/GLOBAL_SETUP_GUIDE.md
  • This Guide: ~/chatmodes/USER_GUIDE.md

Tips for Effective Agent Usage

1. Choose the Right Agent

Match the agent to your task:

  • Coding: Use language-specific agents
  • Reviewing: Use @code-review or @security-review
  • Learning: Use @learning-explainer
  • Debugging: Use @debugging-assistant

2. Provide Context

Give agents enough information:

@python-coding-agent I need to parse a large CSV file (500MB) efficiently. 
The file has 1M rows and 20 columns. I need to:
- Read it in chunks
- Filter rows based on conditions
- Write results to a database

3. Iterate on Responses

Follow up with clarifying questions:

Can you show how to handle errors when the CSV is malformed?
What about memory optimization for even larger files?

4. Combine Agents

Use multiple agents for different aspects:

  1. Generate code with @python-coding-agent
  2. Review it with @code-review
  3. Add tests with @test-generator
  4. Check security with @security-review

5. Learn from Agents

Agents provide educational value:

  • Read their explanations thoroughly
  • Understand the "why" behind suggestions
  • Apply learned patterns to future work

Quick Reference Card

Essential Commands

setup-agents              # Setup in current directory
setup-agents ~/project    # Setup in specific directory
link-agents              # Quick setup (current dir)
ls .github/agents/       # List available agents

VS Code

Ctrl+Shift+I             # Open Copilot Chat
@agent-name              # Use specific agent
Tab                      # Accept suggestion

Common Workflows

New Project:

mkdir project && cd project
git init
code .
# Agents ready!

Existing Project:

cd existing-project
setup-agents
code .
# Agents ready!

Update Agent:

code ~/chatmodes/python-coding-agent.chatmode.md
# Edit and save
# All projects updated!

Support

If you encounter issues not covered in this guide:

  1. Check symlinks: ls -la .github/
  2. Verify agents exist: ls ~/chatmodes/
  3. Restart VS Code
  4. Re-run setup: setup-agents
  5. Check Copilot status: Ensure extension is active

Happy coding with your AI agents! 🚀

Last updated: January 2, 2026