Copilot CLI Builder Skill

Build agents, skills, and prompts for GitHub Copilot CLI.

Copilot CLI Overview

GitHub Copilot CLI is a terminal-native AI agent that:

• •Runs locally with full agentic capabilities (build, edit, debug, refactor)
• •Has GitHub MCP server built-in for repository/issue/PR access
• •Requires explicit user approval for file modifications
• •Supports custom agents, skills, and instructions

Customization Types

When to Use Each

Creating Custom Agents

Custom agents are markdown files with YAML frontmatter defining specialized Copilot behavior.

Agent File Structure

---
name: agent-name
description: Required. What the agent does and when to use it.
tools: ["tool1", "tool2"]
infer: true
---

Agent prompt and instructions in markdown body.
Maximum 30,000 characters.

YAML Properties

Agent Locations

Tool Configuration

All tools (default): Omit tools property or use tools: ["*"]

Specific tools:

tools: ["read", "edit", "search", "execute"]

Disable all tools:

tools: []

Tool Reference

See references/tools.md for complete tool documentation.

Core Tool Aliases:

MCP Server Tools:

• •github/* - All GitHub tools (issues, PRs, repos)
• •playwright/* - Browser automation

Agent Prompt Guidelines

1. •Define Role Clearly: State expertise and responsibilities
2. •Set Boundaries: What the agent should/shouldn't do
3. •Specify Outputs: Expected formats and quality standards
4. •Include Context: Domain-specific knowledge

Agent Examples

Read-Only Explorer:

---
name: code-explorer
description: Analyzes codebases without modifications
tools: ["read", "search"]
---

You explore and explain code. Never modify files.
Focus on architecture, patterns, and dependencies.

Implementation Specialist:

---
name: implementation-planner
description: Creates implementation plans without coding
tools: ["read", "search", "edit"]
---

You create detailed technical plans in markdown.
Never write production code directly.
Focus on specifications, not implementation.

Creating Skills

Skills are packages of knowledge, scripts, and resources that Copilot loads when relevant.

Skill File Structure

skill-name/
├── SKILL.md (required)
└── Optional resources:
    ├── scripts/      - Executable code
    ├── references/   - Documentation for context
    └── assets/       - Templates, images, files

SKILL.md Format

---
name: skill-name
description: What this skill does and when to use it. Include trigger keywords.
license: Optional license info
---

# Skill Title

Instructions and guidance in markdown.
Keep under 5000 words for efficiency.

Skill Locations

Skill Design Principles

1. •Concise is Key: Only include what Copilot doesn't already know
2. •Progressive Disclosure: Core info in SKILL.md, details in references
3. •Trigger Description: Description determines when skill activates

Skill Resource Types

Skill Example

---
name: api-testing
description: Patterns for testing REST APIs. Use when writing API tests, mocking HTTP responses, or validating API contracts.
---

# API Testing

## Quick Start

Use `requests` for synchronous tests:
```python
response = requests.get(url)
assert response.status_code == 200

Patterns

For detailed patterns, see:

• •references/mocking.md - Mock strategies
• •references/assertions.md - Validation patterns

---

## Creating Custom Instructions

Custom instructions provide repository-wide context.

### Instruction File Format

```markdown
---
applyTo: "**/*.ts"  # Optional: glob pattern
---

Instructions for Copilot when working in this repository.

Instruction Locations

Instruction Content Guidelines

• •Repository architecture overview
• •Coding standards and conventions
• •Technology stack details
• •Testing requirements
• •Common patterns to follow

Prompt Engineering Best Practices

Structure Patterns

Role + Task + Constraints:

You are a [role] specializing in [domain].
Your task is to [specific objective].
Constraints:
- Never [prohibited action]
- Always [required behavior]
- Output format: [expected structure]

Context + Examples + Format:

## Context
[Background information]

## Examples
Input: X → Output: Y

## Expected Format
[Template or structure]

Quality Patterns

Anti-Patterns to Avoid

• •Vague descriptions ("help with code")
• •Contradictory instructions
• •Excessive length (>30K chars for agents)
• •Duplicating Copilot's built-in knowledge

Complete Tool Reference

For detailed tool documentation including parameters and examples, see references/tools.md.

Tool Categories

Commonly Used Tools

File Operations:

• •view - Read file contents with line numbers
• •create - Create new files
• •edit - Modify existing files (string replacement)
• •glob - Find files by pattern
• •grep - Search file contents (ripgrep-based)

Execution:

• •powershell - Run shell commands (works on all platforms)
• •Supports sync/async modes
• •Can run Python, Node.js, Go via shell

GitHub MCP Tools:

• •github-mcp-server-list_issues - List issues
• •github-mcp-server-list_pull_requests - List PRs
• •github-mcp-server-search_code - Search code
• •github-mcp-server-get_file_contents - Get remote files
• •github-mcp-server-get_job_logs - Get CI/CD logs

CLI Slash Commands Reference

Decision Framework

Agent vs Skill vs Instructions

Need to restrict available tools?
  → Custom Agent

Need reusable scripts/templates?
  → Skill

Need to teach domain-specific workflow?
  → Skill (with references/)

Need repo-wide coding standards?
  → Custom Instructions

Need path-specific rules?
  → Path Instructions (.github/instructions/)

Tool Selection for Agents

Agent only analyzes code?
  → tools: ["read", "search"]

Agent creates files?
  → tools: ["read", "edit", "search"]

Agent runs tests/builds?
  → tools: ["read", "execute"]

Agent needs full capability?
  → Omit tools property

Validation Checklist

Before Deploying Agent

• • Description clearly states purpose and triggers
• • Tools list matches actual needs (restrictive is safer)
• • Prompt under 30,000 characters
• • Tested with representative prompts
• • File in correct location for scope

Before Deploying Skill

• • SKILL.md has required frontmatter (name, description)
• • Description includes trigger keywords
• • Instructions under 5000 words
• • Scripts tested and working
• • References organized with clear navigation