MCP, agent skills, and CLI tools

Use a skill to describe a repeatable procedure, a CLI for precise local operations, and MCP when an agent needs a discoverable interface to a service. These choices often work together. A bug-triage skill might fetch issues through MCP, run a Python filter through a terminal, and ask the agent to review the resulting shortlist.

The useful decision is where each responsibility belongs. If you put the entire workflow into a tool description, it becomes hard to maintain. If you put every operation into prose, the agent repeatedly reconstructs work that a short program could perform exactly.

This guide follows one task: inspect a small set of GitHub issues, identify bug reports missing reproduction details, and prepare a report for a maintainer. Download the local example to run the data-processing part without credentials or a network connection.

First, separate the responsibilities#

MCP is a protocol used between a host application and servers. Servers can expose tools, resources, and prompts; a server may run locally or remotely. The protocol defines the exchange, while the host decides how to use what it receives. See the MCP architecture overview.

A skill is a package of workflow instructions and supporting files, with SKILL.md as its entry point. A CLI is an executable program operated through arguments, input, output, and an exit status.

The boundaries are a design aid. They are not a claim that MCP only supplies tools or that skills can only contain prose. The MCP Skills extension is one example of these mechanisms overlapping. Verify extension support in your host before depending on it.

Define the result before choosing an integration#

Our triage task has a deliberately modest contract:

• Inspect one identified repository or an explicitly supplied snapshot.
• Consider only records carrying the bug label.
• Identify whether the report includes reproduction steps and expected behavior.
• Produce recommendations with issue numbers and supporting evidence.
• Leave comments, labels, assignments, and issue state unchanged.

That last point matters because “triage” can mean either analysis or mutation. A maintainer asking for a shortlist may not want an agent contacting reporters or rearranging a backlog.

We will use a simple deterministic filter to build the shortlist, then have the skill require a content review. The filter's heading check is intentionally weak: an issue can contain “Steps to reproduce” followed by nothing useful. Separating those stages makes the limitation visible.

Run the local CLI example#

The download contains:

From that directory, run:

The fixture includes three synthetic issues. The observed local result is:

Issue 43 is an enhancement, so it is excluded. Issue 41 contains the two headings; it still needs a human or agent to check whether the steps actually reproduce a problem. Issue 42 lacks those details.

The script validates the input shape, accepts labels represented as strings or name objects, and sorts results by issue number. It does not invoke a shell, access a service, infer severity, or mutate the input file. An issue body is treated as data, even if it contains text resembling a command.

This gives us a repeatable component whose behavior can be checked independently of a model.

Feed it real GitHub data through the CLI#

If you already use an authenticated GitHub CLI, save a bounded snapshot:

Replace OWNER/REPO explicitly. Naming the repository avoids silently querying whichever checkout happens to be current. The selected JSON fields are supported by gh issue list.

This fetches up to 30 matching records. It is a bounded sample, not proof that the repository has only 30 bugs. Record the selection and collection time beside the report. If completeness matters, design pagination and a stopping rule instead of quietly increasing the limit until the output overwhelms the agent.

The command's flags were checked against GitHub CLI 2.97.0. The published result above comes from the local fixture; it is not a claim that we queried a real project's issues for this guide.

Add a skill for the judgment around the program#

The example SKILL.md gives the agent a procedure:

Install the package in your client's supported skill location. The instruction-file guide explains the distinction between a SKILL.md package and standing repository rules.

The skill adds value around the deterministic step. It tells the agent what to ask when repository identity is ambiguous, what a misleading input looks like, and what a finished report should contain. It does not pretend that the Python script understands product behavior.

Keep the script beside the skill when distributing the package. A skill that references a path on its author's laptop is not portable. If the receiving client has no shell, it cannot run the script merely because the file is included; provide another tool or explicitly identify a manual path with weaker reproducibility.

Use MCP when the host needs a service interface#

The same workflow can get its records from GitHub's maintained MCP server. There is no need to write a new server merely to reproduce an existing issue-list capability.

GitHub documents list_issues and issue_read, along with toolset selection and a read-only mode. Configure only the capabilities the task needs, using the official GitHub MCP server documentation. Keep credentials in the host's supported credential mechanism.

Once connected, use a request such as:

The host may add a namespace to the tool name, and the response envelope can differ from the CLI's JSON array. Select the issue array and normalize its fields before passing it to triage.py. Do not blindly run a parser written for one response shape on another.

For a basic connectivity check, request one known issue and compare its number and title with GitHub. That checks the selected repository, credentials, and read path before introducing the larger triage procedure.

This guide does not bundle a custom MCP server or claim that all clients support the same protocol revision. The July 28, 2026 specification changed several protocol mechanisms; follow your installed client's documentation and the server's compatibility guidance instead of treating a release announcement as a compatibility matrix. See the MCP release notes.

Pick the smallest useful integration#

Avoid building a connector, registry, and skill library for a task that runs twice a year. Also avoid embedding business policy in an unversioned prompt that five agents interpret differently every day.

The right amount of structure depends on repetition, failure cost, and the number of people maintaining the workflow.

Account for credentials and authority separately#

A skill can say “read only,” but that sentence does not revoke a write-capable token. A read-only tool surface reduces available actions through that server, but it does not automatically restrict another terminal that has separate credentials.

For this workflow, review three things:

1. Service access: which repositories and operations the credential permits.
2. Available tools: which read and write capabilities the host exposes.
3. Execution access: which files, processes, and network destinations a local command can reach.

A successful authenticated response says the request was allowed. It does not turn text inside an issue into instructions from the task owner. Keep “run this script to fix it” inside an issue body as a claim to inspect, not a command to execute.

For an actual permission lab, use testing coding-agent sandbox access. For this example, begin with a snapshot and read-only operations so that correctness can be evaluated without changing a backlog.

Control output and handle failures#

Context overhead comes from more than the choice of protocol. Long issue bodies, redundant tool descriptions, repeated full snapshots, and recovery attempts can outweigh the initial instructions.

Collect only fields needed for the decision. Save the full snapshot locally when permitted, then provide the agent a shortlist and retrieve additional detail when necessary. Do not strip the evidence the agent needs merely to make the response smaller.

Make failure states explicit:

Test the workflow on both complete and incomplete reports. Then add an issue that contains command-like text, a malformed record, and an empty input set. Useful behavior includes declining to infer facts that are absent.

Connect the workflow in Agentastic#

Agentastic's Plugins & MCP settings configure integrations and deliver them to compatible agents. Its Skills library handles reusable procedures. Issue attachments provide another way to give a run a specific report without asking it to enumerate an entire backlog.

Start with one issue, one procedure, and one inspectable result. Once that is dependable, extend the same design to a scheduled CI diagnostic task, where selection, evidence, and stopping conditions matter even more.

Download Agentastic for macOS to connect the relevant plugin and attach the triage skill to a single, scoped run.

Frequently asked questions#

What is the difference between MCP and agent skills?#

MCP defines an interface through which an application can discover and use server capabilities. A skill packages instructions and supporting files for a workflow. A skill can tell an agent how to use MCP tools, and extensions can distribute skills over MCP.

Can a CLI replace an MCP server?#

Sometimes. If the agent has a shell and a reliable CLI already does the job, that can be sufficient. MCP is useful when a service needs a discoverable structured interface across clients, or the client does not expose a general shell.

Are agent skills executable programs?#

The SKILL.md itself contains instructions and metadata. Its package can also include scripts and other resources, whose execution depends on the host's tools, permissions, and environment.

Which option uses fewer tokens?#

There is no universal winner. Tool descriptions, loaded instructions, output size, retries, and discovery behavior all contribute. Compare completed tasks with the same data and quality bar.

Does connecting an MCP server make its content trustworthy?#

No. Authentication establishes access to a service; it does not make every issue, document, or returned instruction authoritative. Keep retrieved content separate from the authorized task and enforce access limits outside the prompt.