What differentiates on Custom Agents, Agent Skills and Custom Instructions in Copilot CLI

[ans-4175]

Select Topic Area

General

Copilot Feature Area

General

Body

Hi, I’m experimenting with GitHub Copilot CLI and am a bit confused about when to use Custom Agents, Agent Skills, and Custom Instructions, especially for real-world workflows in a codebase.

From the docs, my current understanding is roughly:

Custom agents: specialized versions of Copilot coding agent that you configure as “profiles” for particular workflows, conventions, tools, etc., and then explicitly select (for example via /agent in Copilot CLI or choosing the agent in the UI). They feel like opinionated, persistent teammates that can own an end‑to‑end workflow for a repo or organization.
​

Agent Skills: folders under .github/skills (or .claude/skills) that package instructions + scripts + examples for specific, reusable capabilities (e.g., “webapp-testing”, “github-actions-failure-debugging”). Copilot decides when to load a skill based on its description and my prompt, and the same skill can be reused across Copilot CLI, Copilot coding agent, and VS Code.
​

Repository custom instructions (.github/copilot-instructions.md): always‑on background guidance that sets project‑wide norms (architecture notes, coding standards, how to build/test/deploy, etc.), which Copilot should generally follow for any task in that repo.
​

What is not clear to me is how GitHub envisions these three working together in practice, especially with Copilot CLI:

For something like “diagnose and fix failing GitHub Actions workflows in this monorepo,” should that primarily be:

a custom agent configured for CI/debugging,
one or more Agent Skills (e.g., github-actions-failure-debugging plus repo‑specific skills),

or mostly handled via repository custom instructions with only light use of skills/agents?

Are there recommended rules of thumb such as:

• “Use custom instructions for stable, repo‑wide conventions”
• “Use Agent Skills for portable, task‑specific capabilities”
• “Use custom agents when you want a named persona that consistently orchestrates tools/skills for a workflow”?

In Copilot CLI specifically, are there examples or best practices of how people structure:

one or two general‑purpose custom agents that then rely heavily on skills, versus many narrow custom agents, versus mostly skills + repo instructions and minimal use of custom agents?

Concrete scenarios or patterns used by the Copilot team or other users would be really helpful

Thanks in advance for any clarification or design guidance on how to choose between these options and combine them effectively.

[krishkhinchi]

Hii @ans-4175,

Here’s a clear way to break this down and explain how these three concepts—Custom Agents, Agent Skills, and Repository Custom Instructions—interact in practice, especially in Copilot CLI:

---

1. Repository Custom Instructions (.github/copilot-instructions.md)

• Purpose: Always-on, repo-specific guidance.

• Use case: Enforce stable, repo-wide norms: coding style, architecture notes, build/test/deploy commands, libraries to prefer/avoid.

• Behavior: These instructions are automatically applied whenever Copilot interacts with the repo. They’re passive but persistent.

Rule of thumb:

Use custom instructions for anything that should always apply, regardless of which agent or skill is being used.

Example:

• “All commits must pass lint and unit-tests before merging.”

• “Use TypeScript for backend services and React for frontend components.”

---

2. Agent Skills (.github/skills or .claude/skills)

• Purpose: Encapsulate specific, reusable capabilities that agents can call on-demand.

• Use case: Task-oriented, modular logic that can be shared across agents and repositories.

• Behavior: Skills are invoked automatically by the agent if relevant or can be explicitly invoked in Copilot CLI. They are portable.

Rule of thumb:

Use skills for task-specific logic that can be reused in multiple contexts.

Example:

• github-actions-failure-debugging skill that knows how to parse logs and suggest fixes.

• webapp-testing skill that runs integration tests and reports issues.

---

3. Custom Agents

• Purpose: Define a persona or workflow orchestrator that can combine skills and instructions.

• Use case: When you want a named, persistent “agent” that handles complex workflows end-to-end.

• Behavior: Custom agents select skills, follow repo instructions, and manage task orchestration in a consistent way.

Rule of thumb:

Use custom agents when you want a consistent helper that can handle multi-step workflows or complex tasks.

Example:

• A CI-Debugger agent that automatically:

  1. Reads failing GitHub Actions logs.

  2. Applies github-actions-failure-debugging skill.

  3. Suggests code fixes or workflow updates.

---

How They Work Together

For a workflow like “diagnose and fix failing GitHub Actions workflows in a monorepo”:

Component | Role -- | -- Repository Custom Instructions | Provide project-specific context (CI setup, test commands, repo structure). Agent Skills | Encapsulate the task-specific logic (github-actions-failure-debugging, parsing logs, suggesting fixes). Custom Agent | Orchestrates the workflow, deciding when and which skills to apply, interacts with CLI prompts, and provides a “persona” that understands the repo.

Recommended pattern:

1. Always define repo-wide instructions for consistent context.

2. Create modular skills for repeatable, task-specific logic.

3. Use custom agents only when you need a named, orchestrated persona to handle complex workflows or multiple skills together.

---

Practical Copilot CLI Example

# repo instructions: .github/copilot-instructions.md
- Use npm for all JS builds
- Run `lint` and `test` before PRs
- CI runs on GitHub Actions
agent skill: .github/skills/github-actions-failure-debugging

Analyze failed workflow logs
Suggest fixes for common errors (missing env, syntax, test failures)
Provide commands to retry

custom agent: ci-debugger-agent

Persona: “CI Debugging Expert”
Steps:

Scan failed workflows
Call github-actions-failure-debugging skill
Suggest code/workflow fixes
Follow repo instructions

With this setup, you get reusable skills, repo-specific guidance, and a named agent that orchestrates everything.

[krishkhinchi]

If this answer solve your all doubts so can you please mark my answer as solved/answered
or if did not solved yet so please tell me your doubt

[ans-4175]

Hi @krishkhinchi thanks for answering all the questions. It is completely answered my inquire :)

[ksachdeva]

Unfortunately the answer related to "prompt" aspect is not correct. In a prompt file, you can specify the tools.

See one of the examples here -
https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/prompts/conventional-commit.prompt.md

[Carbaz]

Unfortunately the answer related to "prompt" aspect is not correct. In a prompt file, you can specify the tools.

See one of the examples here - https://raw.githubusercontent.com/github/awesome-copilot/refs/heads/main/prompts/conventional-commit.prompt.md

Yeah, that’s right. What I understood from his answer, and from some additional research, is this:

Prompts are simply prompts. They are structured text that you invoke directly from the chat whenever you want to use them. They can guide or suggest tool usage, but they do not package their own tools. They are reusable prompt workflows that you choose explicitly.

Skills are different. They are a packaged capability that can include their own resources or tools, and they extend what the agent can do.

The second important distinction is this. Prompts must be called explicitly by the user, while skills can be activated automatically by agents when they are relevant, without you having to request them directly.

[IeuanWalker]

@krishkhinchi how does this work with the SDK?

As someone who is building an application with the SDK, how do I wire everything up to work as it does with the cli?

[scott-goodrow-benchling]

Are agent skills supported by Copilot's review agent?