2dayapp
Category
Engineering
Published
Read time
11 min

Custom Agent, Skill, MCP, or Hook?

A decision guide for Custom Agents, Skills, MCP servers, Hooks, and Subagents based on role, reusable workflow, external tools, and execution timing.

한국어 버전 보기

AI coding tools now expose several layers of customization at once. You can define a Custom Agent, create a Skill, connect an MCP server, or attach a Hook. They all change what the agent can do, but they solve different problems.

Use four questions to choose the right layer:

The compact version is: a Custom Agent defines the role, a Skill defines the method, MCP provides the connection, and a Hook defines the timing.

One distinction matters before going further. A Custom Agent and a Subagent are not synonyms. A Custom Agent is a role configuration. A Subagent is delegated execution in a separate context. Depending on the product, the same Custom Agent can run as the primary agent or be invoked as a Subagent.

Codex, Claude Code, and GitHub Copilot use similar terms, but their file locations and execution details are not identical. The decision model below is shared; the configuration syntax is not always portable.

The four layers change different things

Layer What it changes Good fit Typical artifact
Custom Agent Role, model, and tool boundary Security reviewer, documentation specialist, test specialist Agent profile
Skill Repeatable procedure and domain knowledge Release, code review, incident analysis SKILL.md, references, scripts
MCP Data and actions outside built-in tools GitHub, Figma, Sentry, local browser MCP server and tool configuration
Hook Code that runs around lifecycle events Secret scan, command block, lint, audit log Event-to-command configuration

The key is to identify what is changing. A Custom Agent changes who is acting and which tools that role may use. A Skill adds a method to the current agent. MCP expands the available capabilities. A Hook runs code when an event occurs instead of waiting for the model to remember a step.

A Custom Agent is a reusable role profile

A Custom Agent packages a role, system prompt, model choice, and tool scope. It is useful when “review this code carefully” has become a repeated role with a stable output format and permission boundary.

A read-only regression reviewer, for example, can receive search and file-read tools without edit access. An implementation agent can receive edit and test tools. The role configuration stays reusable across tasks.

That does not mean every Custom Agent runs in a separate context. It may be selected as the primary agent. It may also be delegated work as a Subagent, in which case the isolated execution context is a property of the delegation.

GitHub Copilot Custom Agents can define a name, description, prompt, tools, and agent-specific MCP servers. Claude Code Subagents can have their own system prompt, tools, model, permission mode, and preloaded Skills.

This minimal GitHub Copilot agent profile describes a read-only review role:

---
name: regression-reviewer
description: Finds behavioral regressions and missing tests in a code change.
tools: [read, search]
---

Compare the requested behavior with the actual control flow.
Report only reproducible findings. Do not modify code files.

Create a Custom Agent when:

If the role stays the same and only the procedure repeats, a Skill is the smaller unit.

A Skill is a reusable way of working

A Skill packages instructions for a specific kind of task. It may be instruction-only or include references and helper scripts.

Suppose every pull-request review repeats these requirements:

That does not require a new worker. It requires the same review method to be available to whichever agent is active.

Codex Skills use a SKILL.md file with optional scripts, references, and assets. Codex initially sees the Skill name and description, then loads the full instructions and supporting material when the Skill is selected.

---
name: regression-review
description: Find behavioral regressions and missing verification in code changes.
---

1. Compare the requested behavior with the diff.
2. Trace changed control flow and state transitions.
3. Report only reproducible findings with severity.
4. Run relevant tests and summarize residual risk.

Create a Skill when:

A Skill does not create new access. Writing “check Sentry” in SKILL.md does not give the agent a Sentry tool. That capability must come from MCP, a connector, or another approved tool.

MCP adds capabilities outside the built-in tool set

Model Context Protocol lets an agent use tools, resources, and prompts exposed by a server. The server may be remote, such as GitHub or Sentry, or local, such as a browser, database, or development utility.

These tasks require more than a Skill:

MCP provides the authenticated tool boundary. A Skill can then define the order in which those tools should be used.

Codex supports local STDIO servers and Streamable HTTP servers. A narrow configuration exposes only the tools that the workflow needs:

[mcp_servers.issue_tracker]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "ISSUE_TRACKER_TOKEN"
enabled_tools = ["search_issues", "get_issue"]
default_tools_approval_mode = "writes"

The important decision is not simply whether the server connects. It is which tools become available. A read-only research agent does not need issue deletion or mutation tools. Limit the tool list and keep writes behind a separate approval boundary.

Use MCP when:

Avoid burying an entire business workflow in MCP server instructions. Server-wide constraints and cross-tool limits belong there. A task-specific procedure such as incident triage belongs in a Skill, where it can be reused and changed independently.

A Hook defines when code runs

A Skill is a method the agent chooses to use. A Codex Hook attaches code to lifecycle events such as session start, prompt submission, before or after a tool call, a permission request, or the end of a turn.

Hooks fit requirements such as:

This example runs a policy script from the repository root before a shell tool call:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/check_agent_command.py\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Use a Hook when the action has a precise event and a machine-checkable result. Secret-pattern checks, explicit command blocks, formatting, and audit events are better starting points than a vague instruction to “improve quality when the task ends.”

Hooks are more predictable than asking the model to remember a step, but they are not an absolute guarantee. A local Hook may be disabled or skipped when a project is not trusted, and event support varies by product and surface. Merge-blocking checks still belong in CI and branch protection. The permission boundary around Hooks and tools is covered in AI coding agent auto-approval.

How the layers work together

An incident-analysis workflow often grows through these layers rather than starting with all of them.

The first version may be a Skill that defines triage steps. When the workflow needs current Sentry data, add MCP. When the same read-only role appears repeatedly, define a Custom Agent. If the investigation begins consuming the main context, delegate that role as a Subagent. If production commands must be blocked during the investigation, add a Hook or managed permission policy.

Incident-analysis Custom Agent (delegated as a Subagent)
  └─ Incident-analysis Skill
       ├─ Sentry MCP retrieves error events
       ├─ GitHub MCP finds related issues
       └─ PreToolUse Hook blocks operational commands

Each layer has one responsibility:

  1. The Custom Agent defines the read-only analysis role; Subagent execution provides a separate context.
  2. The Skill defines collection, reproduction, hypothesis, and verification steps.
  3. MCP provides current Sentry and GitHub data.
  4. The Hook checks that the analysis role does not invoke an operational command.

This separation makes change cheaper. Update the Skill when the triage procedure changes. Update MCP when the integration changes. Update the Agent when the role changes. Update the Hook or managed policy when enforcement changes.

A practical decision order

Do not create an Agent for every new instruction. Work through these questions in order.

Is it needed only for this task?

Keep it in the prompt. Turning an unproven one-off procedure into permanent configuration creates maintenance before reuse exists.

Does it apply to every task in the repository?

Build commands, directory structure, and universal verification rules belong in AGENTS.md or the product’s project instructions. A long release procedure does not belong in always-loaded repository guidance.

Is it a repeatable procedure?

Package release, review, and incident-analysis workflows as Skills when the input changes but the operating sequence remains stable.

Does it need a missing capability?

Connect MCP when the agent needs data or actions outside its built-in tools. Expose only the required tools and separate reads from writes.

Does it need a reusable role or separate context?

Define a Custom Agent for a reusable role and tool boundary. Delegate it as a Subagent when a large or independent task should not fill the primary context.

Does code need to run at a known event?

Use a Hook for session-local automation and additional guardrails. Use CI when a repository rule must pass before merge.

Common design mistakes

Making every procedure an Agent

A test runner, commit-message writer, and spelling checker do not all need separate role profiles. If a task does not need a distinct role or tool boundary, a Skill or ordinary command is usually enough.

Putting authentication instructions in a Skill

A long sequence of curl commands and token-handling instructions mixes connection mechanics with the workflow. Provide external access through MCP or a purpose-built CLI. Let the Skill focus on how to use that tool.

Putting business judgment in an MCP server

MCP is good at defining tool and data boundaries. Team review criteria and release decisions are task-specific judgment. Keep them in a Skill or Agent role rather than loading them as server-wide instructions.

Treating a Hook as the entire security boundary

Hook execution depends on environment and trust state. String matching also cannot understand every shell side effect. Start with a sandbox and permission policy, then use Hooks as another defense layer.

Copying the same rule everywhere

Repeating “never modify the production database” in the Agent, Skill, MCP description, and Hook makes ownership unclear. Put the policy where people and the model can read it. Enforce the machine-checkable part with permissions and Hooks.

Start with the smallest useful configuration

A small project rarely needs all four layers on day one.

  1. Keep shared repository rules in a short AGENTS.md.
  2. Turn a procedure into a Skill after it repeats.
  3. Add MCP when a workflow needs a real external capability.
  4. Define a Custom Agent when a role or tool boundary becomes reusable.
  5. Add a Hook or CI check after a validation step is actually missed.

The goal is not to minimize features. It is to know which layer to fix when behavior fails.

If the role is wrong, inspect the Custom Agent. If the steps are incomplete, fix the Skill. If data cannot be retrieved, inspect MCP and tool exposure. If an event check did not run, inspect the Hook and CI path.

Conclusion

Custom Agents, Skills, MCP servers, and Hooks extend AI coding tools along different axes. A Subagent describes delegated execution rather than another kind of configuration.

When the choice is unclear, ask what needs to change: the role, the method, the available capability, or the execution timing. If the answer includes more than one axis, split the responsibilities instead of forcing the entire workflow into one feature.