GitHub Copilot Custom Agents vs Skills

You’re using GitHub Copilot in VS Code. It’s great for code completion, but you want more control. Maybe you need it to follow your team’s specific patterns, or you want it to know about your iOS architecture.

There are two ways to customize Copilot behavior:

Custom Agents — You manually switch to them (like @plan or @security)

Skills — Copilot loads them automatically when relevant

This post covers both and shows you when to use each.

Before we begin

• Make sure you have VS Code with GitHub Copilot installed
• Basic understanding of how Copilot Chat works
• A project you want to customize Copilot for

The Key Difference

Feature	Custom Agents	Skills
Activation	Manual - you select @agent	Automatic - loads when relevant
File Format	.agent.md	Directory with SKILL.md
Best For	Controlled workflows	Domain knowledge
Tool Control	Can restrict tools	Full access
Handoffs	Yes - sequential steps	No

Think of it this way:

• Agents = Different team members you switch between
• Skills = Reference docs that appear when needed

Custom Agents: The Manual Mode

Agents are specialized personas. When you switch to an agent, you’re telling Copilot to act a specific way with specific constraints.

The Agent File

Create .github/agents/plan.agent.md:

# Plan Agent

## Description
Architecture specialist. Read-only mode to prevent code changes during design.

## Instructions
Focus on:
- High-level architecture decisions
- Scalability and maintainability
- Existing patterns in the codebase
- Create diagrams when helpful (mermaid)

Never implement — only design.

## Model
claude-3.5-sonnet

## Tools
- workspace_context (read-only)
- search (read-only)

## Handoffs
### Start Implementation
Ready to code? Click here to switch to the Coder agent.

Why This Works

Tool Restriction: The plan agent can’t accidentally modify code. It’s read-only.

Model Choice: Claude 3.5 Sonnet for complex reasoning. You could use GPT-4o for faster responses.

Handoffs: The “Start Implementation” button creates a smooth workflow. Plan → (click) → Code.

Using the Agent

1. Open Copilot Chat in VS Code
2. Click the agent dropdown (top of chat)
3. Select “@plan”
4. Ask: “Design a payment service architecture”
5. Agent responds with read-only analysis
6. Click the handoff button to switch to coding

iOS Architecture Agent

Create .github/agents/ios-architect.agent.md:

# iOS Architect

## Instructions
You design SwiftUI + TCA architectures for iOS apps.

Follow these patterns:
- Modular feature separation
- async/await for Swift 5.5+
- The Composable Architecture for state management
- Apple's Human Interface Guidelines

Recommend MVVM, Coordinator, or TCA patterns based on complexity.

## Model
claude-3.5-sonnet

## Handoffs
### Start Implementation
Architecture approved? Switch to iOS Coder.

Now when you type @ios-architect "Design a profile screen with edit mode", you get iOS-specific architecture guidance without any code changes.

Agent Skills: The Auto-Load

Skills are different. You don’t switch to them — Copilot reads their descriptions and loads them automatically when relevant.

The Skill Structure

.github/skills/
└── ios-testing/
    ├── SKILL.md              # Core instructions
    ├── test-template.swift   # Reusable template
    └── mock-data.json        # Example fixtures

Creating Your First Skill

Create .github/skills/ios-testing/SKILL.md:

# iOS Testing Skill

## Description
XCTest patterns and templates for iOS unit tests.

## When to Activate
- User asks about testing iOS code
- Working in *Tests.swift files
- User mentions XCTest or test coverage

## Instructions

Follow Given-When-Then pattern:

```swift
func test_login_withValidCredentials_returnsSuccess() {
    // Given
    let credentials = Credentials(user: "test", pass: "valid")
    let mockAuth = MockAuthService()

    // When
    let result = sut.login(credentials: credentials)

    // Then
    XCTAssertTrue(result.isSuccess)
    XCTAssertEqual(mockAuth.loginCallCount, 1)
}

Name tests: test_methodName_condition_expectedResult

Now add the template file.

Create `.github/skills/ios-testing/test-template.swift`:

```swift
import XCTest
@testable import YourApp

final class FeatureTests: XCTestCase {
    var sut: YourFeature!

    override func setUp() {
        super.setUp()
        sut = YourFeature()
    }

    override func tearDown() {
        sut = nil
        super.tearDown()
    }

    func test_example() {
        // Given

        // When

        // Then
        XCTAssertTrue(true)
    }
}

How It Works

You don’t activate this skill manually. Just start working:

1. Open a file like LoginViewModelTests.swift
2. Ask Copilot: “Add tests for login validation”
3. Copilot sees you’re in a test file
4. Reads the skill description: “activate when working in *Tests.swift files”
5. Loads the skill automatically
6. Uses your template and patterns

No @skill command needed. It just works.

When to Use Which?

Use Custom Agents when:

• You need strict tool control (read-only, no terminal)
• You want specific model selection
• You have multi-step workflows (plan → code → review)
• You need role-based behavior (security mindset, QA perspective)

Use Skills when:

• You want automatic augmentation
• You have reusable templates and code
• You need domain expertise (iOS patterns, API integrations)
• You want it to work across VS Code and CLI

Most teams use both.

Using Both Together

Here’s a real workflow: implementing Apple Pay in an iOS app.

Step 1: Planning (Agent)

You: @plan "Add Apple Pay support"

[Plan Agent activates]

Plan Agent:
- Analyzes existing payment code
- Suggests modular payment service
- Creates architecture diagram
- No code written (read-only)

[Handoff Button] → Code Agent

Step 2: Implementation (Agent + Skills)

You: [Clicks handoff]

[Code Agent activates]
[iOS Patterns Skill auto-loads]
[iOS Testing Skill auto-loads]

Code Agent:
- Creates PaymentService.swift
- Uses async/await patterns from iOS skill
- Follows your team's architecture

You: "Add tests"

[Testing skill already loaded]

Code Agent:
- Uses test-template.swift from skill
- Follows Given-When-Then pattern
- Creates PaymentServiceTests.swift

Step 3: Security Review (Agent)

[Code Agent] [Handoff Button] → Security Agent

You: [Clicks handoff]

[Security Agent activates - read-only]

Security Agent:
- Checks for hardcoded keys
- Verifies secure credential storage
- Reviews API key handling
- No code changes (read-only mode)

The workflow: Plan (read-only) → Code (with skills) → Review (read-only)

Team Rollout Strategy

Week 1-2: Start with skills

• Create 2-3 essential skills (testing, architecture, style guide)
• Zero workflow changes for the team
• Copilot just gets smarter

Week 3-4: Add process agents

• Create plan and review agents
• 30-minute team training on handoffs
• Optional usage

Month 2+: Expand

• Team creates project-specific agents
• Add more domain skills
• Customize workflows

Common Mistakes

Mistake 1: Too many agents (10+)

Fix: Keep 3-5 core agents. Move knowledge to skills instead.

Mistake 2: Generic skills like “General iOS Skill”

Fix: Create focused skills: “iOS Testing”, “iOS Networking”, “iOS UI”. Copilot loads multiple simultaneously.

Mistake 3: Forgetting handoffs

Fix: Always add handoff buttons in agents. Make the next step obvious.

Conclusion

You now know the difference between Custom Agents and Skills:

• Agents = Manual activation, strict control, workflow orchestration
• Skills = Automatic activation, knowledge augmentation, portable

Start with 2-3 skills for your team. They provide immediate value with zero friction. Then add process agents for key workflow steps.

Next up: We’ll build a complete iOS development workflow with agents, skills, and MCP integration for Notion task management.