Skill Instructions

Overview

GitHub Copilot provides seven customization features that allow you to tailor how the AI assistant behaves in your workspace. These features enable you to define coding standards, create reusable workflows, build specialized tools, and control how guidance is applied across your codebase. Each feature serves a distinct purpose—from always-on workspace rules to explicit user-invoked prompts—and choosing the right one depends on your specific needs.

This skill helps you:

• Understand the seven feature types and when to use each one
• Select the appropriate feature based on your requirements
• Format and structure each feature type correctly
• Navigate detailed documentation for implementation

How to Use this Skill

CRITICAL: The current file is just an overview, but the files linked have much more information. Once a feature type is selected, you MUST read the associated linked file for much more information.

Use the Feature Reference for quick lookup, the Feature Selection Guide to make informed choices, and the linked documentation for comprehensive implementation guidance.

See also the Global Rules section for important rules which apply when creating or editing all features.

Feature Reference

.github/copilot-instructions.md

applyTo

.github/instructions/*.instructions.md

AGENTS.md

description

.github/skills/<name>/SKILL.md

.github/prompts/<name>.prompt.md

.github/agents/<name>.agent.md

.github/hooks/*.json

.claude/settings.json

Feature Purposes

• Custom Instructions – Define workspace-wide rules, standards, and conventions that are automatically applied to every chat request in the workspace. Use for guidance that affects all development work.
• Instructions Files – Define scoped instructions for specific files, languages, or folders that activate based on file patterns or semantic task matching. Use when rules should apply only to certain contexts.
• AGENTS.md – Provide custom instructions intended for all agents in the workspace, designed to be tool-agnostic and work across multiple AI assistants (GitHub Copilot, Claude Code, etc.).
• Agent Skills – Provide specialized, reusable capabilities with optional bundled assets (scripts, templates, checklists) that load on demand when requests match the skill description or when invoked via slash commands.
• Prompt Files – Provide explicit, reusable prompts for repeatable tasks that users invoke deliberately through slash commands, the command palette, or editor buttons.
• Custom Agents – Define specialist assistants with explicit scope, tool restrictions, and constraints for role-specific workflows like planning, code review, or research.
• Agent Hooks – Execute custom shell commands deterministically at specific agent lifecycle points (SessionStart, PreToolUse, PostToolUse, etc.) to enforce security policies, automate quality checks, create audit trails, or inject context.

Feature Selection Guide

When to Use Each Feature

Use this flow to quickly choose the right feature type:

applyTo

description

Important: Only one slash command can be used at a time. This includes skills and prompt files invoked via slash commands, so you cannot manually select multiple skills/prompts in a single request.

Comparing Across Features

Use these criteria when choosing between similar feature types:

Instructions Files vs Agent Skills

• Does this apply to most work in a domain? → Instructions Files
• Does this apply to specific tasks or workflows? → Agent Skills
• Example: "Always use type hints in Python" → Instructions. "Generate Jest tests with mocks" → Skill.

Agent Skills vs Prompt Files

• Multi-step workflow with bundled assets (scripts, templates)? → Agent Skills
• Single focused task with parameterized inputs? → Prompt Files
• Example: "Security audit with checklist + scripts" → Skill. "Generate API route from method + path" → Prompt.

Agent Skills vs Custom Agents

• Same capabilities needed for all steps? → Agent Skills
• Need context isolation (subagent returns single output)? → Custom Agents
• Need different tool restrictions per stage? → Custom Agents
• Example: "Generate tests following team standards" → Skill. "Plan feature (read-only) → Implement → Review (different tools each stage)" → Custom Agents.

Custom Instructions vs AGENTS.md

• GitHub Copilot-specific standards? → Custom instructions
• Tool-agnostic rules for multiple AI assistants? → AGENTS.md
• Use both when needed; they complement each other.

Instructions/Skills vs Agent Hooks

• Need to guide agent behavior? → Instructions or Skills
• Need guaranteed deterministic execution? → Agent Hooks
• Need to block operations before they execute? → Agent Hooks (PreToolUse)
• Need to run code at specific lifecycle points? → Agent Hooks
• Example: "Always validate inputs" → Instructions. "Run linter after every file edit" → Hook.

Global rules

Naming

• Use lowercase, hyphen-separated names for variable-name features (skills, prompts, agents).
• Avoid generic names (e.g., "testing", "instructions", "standards").
• Use descriptive, action-oriented names that indicate purpose or capability (e.g.,

  jest-test-generation

  ,

  generate-api-route

  ,

  code-reviewer

  ).
• Fixed-name features (custom instructions, AGENTS.md) have specific filenames; no variation needed.

Other Rules

• For Agent Skills, the

  description

  is the only text used for automatic activation. It must state capability and when to use it.
• For Prompt Files and Custom Agents, the

  description

  is UI metadata; make it specific and task-focused.
• For Custom Instructions and AGENTS.md, do not use YAML frontmatter.
• Include one concrete example per feature type.

For detailed guidance on phrasing rules, constraints, and instructions, reference the writing-ai-instructions skill.

Validation Checklist

• Name is lowercase and hyphen-separated (skills, prompts, agents)
• File path matches feature type
• Examples are included