Practical agent workflows · · 15 min read
MCP, skills and hooks: choose the right agent extension
A working map of tools, reusable instructions and lifecycle events, with a small fixture that separates availability, permission and actual use.
A coding agent can have a useful tool, a carefully written workflow and an automatic command around every tool call. Those three things may appear together, yet they solve different problems. When one of them fails, reinstalling all three makes the system harder to understand. A better starting point is to identify whether you need a capability, instructions for using it, or a deterministic reaction to an event.
This guide uses an illustrative release review for a small web application. The agent must inspect an issue, modify one checkout, run the relevant checks and prepare a reviewable result. GrantTap supplies the mobile view of the Task and supported decisions; it does not turn a missing provider integration into a working tool. The examples below are a planning and verification method, not a report that these actions happened in your account. Keep provider versions and the selected computer visible as you follow the exercise.
Try a focused check
Use a dedicated test Task and the intended authorized working directory.
State the missing behavior
Name the operation, reusable guidance or event you need. Do not install all three mechanisms by default.
Goal: inspect one fixture file Allowed scope: the dedicated test folder Expected evidence: operation result and correlation Negative case: outside that scope remains deniedTest a single fixture
Use a harmless dedicated task and record both the allowed result and the expected refusal. A catalog entry alone is not proof of use.
Check the boundary
Keep provider permissions, GrantTap policy and confirmed execution separate in the result.
Start with the missing outcome
Suppose the agent says that a customer reported a broken checkout. You need it to retrieve the relevant issue from your tracker. That is a capability problem: the agent needs an authorized way to read that external service. A paragraph telling the agent to consult the tracker cannot create that connection. Write the desired result as a narrow operation: read issue ABC-42 from the chosen workspace, return its current status and preserve the link. This makes it possible to verify both access and the specific result.
Now suppose the tracker connection works, but the agent jumps straight from the report to changing code. Your team requires a reproduction before an edit. That is a workflow problem. The missing information is the order of work, the evidence to retain and the condition for proceeding. A skill can package that repeatable procedure, its examples and supporting resources. An external connection may help the procedure, but instructions remain useful when the inputs are local files or information already provided by the person.
Finally, suppose every shell command should pass an installed validation step before execution. The agent remembering a sentence is insufficient for that requirement. You need to inspect the provider's supported hook point, its configuration and its actual decision behavior. Some hooks observe events; others can influence a supported operation. Name the event and the expected result before choosing a mechanism. That small distinction prevents a monitoring script from being described as an enforcement boundary it never implemented.
Understand the three contracts
An MCP connection exposes a service's capabilities to a compatible client. Its availability depends on the server, transport, authentication and the host's configuration. In practice, asking whether MCP is working is too broad. Ask whether this client initialized this server, whether the intended operation appears and whether an authorized call returns the expected data. The Claude Code MCP documentation is the primary reference for that client's setup; another coding application can have different connection and approval behavior.
A skill describes a way to perform a task. It may include instructions, examples, scripts and references, with the exact packaging and discovery rules defined by its host. The OpenAI skills overview distinguishes repeatable workflow guidance from live service access. That distinction is especially useful during a handoff: a colleague can receive the procedure while still lacking the service permission needed for one step. Treat the procedure's presence and its executable prerequisites as separate checklist items.
A hook responds at a documented point in the provider's lifecycle. Its authority comes from that hook contract and the process that runs it. A script that logs completion is different from a pre-action check that can refuse a supported command. The Claude Code hooks reference explains its event-specific behavior. For a real deployment, record the chosen event, relevant input, expected exit behavior and any supported decision output. The label hook alone does not establish what the provider will do.
Choose the smallest useful combination
For the example release review, begin with the issue reader and the repository already on the computer. You may need one MCP connection for the issue tracker and one skill describing the review procedure. A hook is justified only when you have an event-specific requirement, such as an existing team rule that must be checked before a supported tool operation. Installing a hook because a skill exists adds maintenance without necessarily adding a useful outcome. Every additional process, credential and configuration scope creates another item to inspect when work stops.
Create a small ownership note before installation. The issue-tracker connection owns external access. The review skill owns the sequence and expected evidence. The provider owns execution and its native permissions. GrantTap carries the supported Task view and decisions for the selected computer. This note does not need an architecture diagram or a policy engine. Four clear sentences are enough to stop a later troubleshooting session from assigning the same responsibility to three different components.
Prefer a missing feature with a precise fallback over an improvised imitation. If the tracker tool cannot read attachments, say that the exercise uses the issue text and a separately supplied sample attachment. If the provider lacks a required hook event, keep that requirement unmet and use a manual checkpoint for the example. Do not silently substitute a different operation while reporting that the original check passed. An explicit gap makes the eventual implementation smaller because it preserves the real acceptance criterion.
Install into the scope that owns the work
Consider a skill intended only for one repository. Placing it in a machine-wide location can make unrelated agents discover instructions that were written for a different project. Conversely, installing a required server only in an editor's temporary workspace can leave a headless continuation without the same capability. Make a short scope inventory: the coding client, the profile or project that holds the configuration, the repository path and the process expected to consume it. Verify those facts on the computer where execution will occur.
Use a harmless probe that proves the intended scope. A local fixture file can contain a short unique marker and an intentionally obvious expected answer. Ask the selected agent to read that marker using the workflow being configured. For an external reader, use a dedicated test issue with no customer data and an equally clear expected result. The marker helps distinguish a fresh tool result from an earlier message, another project's resource or an answer inferred from the prompt. Remove private values from any screenshots you retain.
Then start a second conversation in an unrelated project and inspect availability there. The expected result depends on your chosen configuration scope: a project-only setup should remain project-only, while a deliberately global server may appear in both. The purpose is to learn what you actually installed, not to make every scope identical. A failed scope check is a configuration finding. Fix it where the configuration lives rather than adding another copy of the same server under a different name.
Verify availability, permission and actual use separately
A server listed in a catalog is an availability observation. A rule allowing its tool is a policy decision. A successful invocation is evidence that a particular call happened. These are different facts with different lifetimes. A server can remain configured while its credentials expire. A permitted operation can fail at the external service. A selected skill can be available without the agent following its procedure on the current turn. Build your evidence note around those differences instead of giving the whole setup a single green badge.
For the sample issue reader, record the initialized server identity and the exact operation used. Next record whether permission was requested or already allowed under the effective policy. Finally keep the returned issue identifier and a bounded result that can be checked against the fixture. You do not need to retain an entire issue payload or a credential-bearing request. A short result, source link, observation time and computer name are more useful than a large debug dump that nobody can safely share.
GrantTap's capability and usage views should be read with the same discipline. Available, selected, accepted and used do not mean the same thing. When an observation is missing, keep it unknown. See the capability setup guide for the current product route and its limits. If the phone shows a Task but not a particular tool invocation, inspect the provider's native evidence before claiming the tool did not run. Missing visibility and failed execution require different fixes.
Make a skill produce a reviewable artifact
Write the release-review skill around outputs a colleague can inspect. The first section should say what inputs are required: a repository, a concrete issue and the behavior under review. The procedure can then ask for a reproduction, a minimal change and relevant checks. Its final output should distinguish what changed, what was verified and what remains unresolved. Avoid making the skill a large collection of slogans. A short instruction attached to a real example is easier to follow and easier to maintain.
For a practice run, deliberately provide an issue with one missing detail, such as the affected browser. A useful procedure should identify that gap instead of inventing an environment. Then provide a second fixture with all required information and compare the resulting artifact. This pair reveals whether the skill helps the agent select evidence or merely produces a consistent-looking final paragraph. Keep both fixtures small so a future change to the skill can be checked without running an entire release process.
Give the procedure a clear completion boundary. Preparing a review does not necessarily authorize publishing the application, merging a branch or messaging a customer. State which of those actions belongs to the exercise and which requires a separate instruction. This is not a request for an approval prompt before every reversible edit. It is a way to ensure that a repeatable workflow does not silently widen its own objective when a tool becomes available. Tool access should serve the user's task rather than define it.
Test hooks with an observable positive and negative case
A hook deserves a test that demonstrates its specific contract. For an observer, arrange one supported event and verify one corresponding record. For a check that can reject an operation, use a harmless synthetic command or test fixture that exercises the rejection path without deleting files or reaching production. Pair it with an allowed case. A positive-only test can establish that the script runs while leaving you unaware that its denial output is ignored by the host or attached to the wrong lifecycle event.
Inspect behavior when the hook itself fails. A missing executable, a timeout and malformed output are different failures. The provider may define how each is treated, and that behavior can depend on the event. In the release-review example, the expected result is an explicit configuration finding and enough information to repair the failing component. Repeatedly running the original business operation is a poor diagnostic when the broken part is a prerequisite. Fix the prerequisite first, then repeat the bounded fixture once.
Keep hook logs proportionate to the problem. Useful fields include an event name, a local correlation identifier, a coarse outcome and elapsed time. Avoid recording the entire tool input by default, because it can contain file contents or credentials. If you need a specific argument to explain a failure, create a synthetic example that demonstrates it. A smaller record makes troubleshooting faster and also makes it possible to compare two runs without hunting through unrelated conversation text or private customer data.
Diagnose the layer that actually failed
Imagine that the issue reader works in the desktop client, but a continuation from the phone reports it unavailable. Compare the execution computer and native session first. Then compare the provider's configuration scope and initialized capabilities. Reinstalling the mobile application is unlikely to repair a project-only server configuration on the Mac. Likewise, clearing a phone cache does not refresh an external provider's credentials. The fastest path is usually the smallest experiment that separates route selection from capability initialization.
Now imagine that the agent reads the issue but skips the reproduction. Inspect whether the skill was discovered, whether its instructions fit the task and whether the inputs were sufficient. Ask for the missing artifact rather than declaring the external reader broken. If a hook failed before the read began, inspect its exact error and provider event separately. This diagnostic sequence gives each failure a responsible component. It also prevents one visible symptom, such as no answer on the phone, from being treated as proof that every part of the stack failed.
For a team handoff, transfer a compact configuration receipt. Include the relevant repository, client and computer, the skill identity, the initialized server and the harmless fixture result. Include limitations and any outstanding authentication step. Do not transfer live tokens, pairing codes or an unrestricted archive of configuration directories. The recipient should be able to reproduce the same small check with their own authorized connection. A list of installed names without those checks creates apparent consistency while leaving the actual working environment uncertain.
Maintain the setup as a small product
Treat a reusable agent workflow as something with an owner and a review trigger. When the external tool schema changes, review the step that uses it. When a provider changes a hook contract, repeat the hook's positive and negative fixture. When a repository changes its test command, update the skill's example and verify the new command in the correct checkout. Those triggers are more useful than a blanket rule to reinstall everything periodically. Each change has a reason and a bounded check that can confirm its effect.
Before removing a component, identify what depends on it. A server used only by this skill may be removable from that project, while a global connection might support several other workflows. Disabling a hook changes the behavior of its event, so record whether the system is now observing, enforcing or leaving that check manual. The goal is not to preserve every integration forever. It is to make a removal just as understandable as an installation, with the next person able to see which outcome changed.
Finish the exercise with a short acceptance note in ordinary language. The correct agent on the correct computer read the test issue through the intended connection, followed the review procedure and produced a bounded result. The chosen hook, if any, handled its allowed and rejected fixtures as documented. GrantTap displayed only the evidence its current integration supports. Anything else remains a named gap. That note turns MCP, skills and hooks from a collection of installed labels into a workflow you can explain, repeat and safely change.
Check the cost before adding another background component
A working setup can still be unnecessarily expensive. Measure a quiet minute before and after enabling a hook or server, then repeat a small representative operation. Record the process that changed, the sample duration and whether the agent was actually idle. One brief CPU reading during a repository scan is different from repeated background work after every turn has ended. This exercise does not need a universal performance target: it needs an explanation of which component was doing useful work and whether that work stopped when its job ended.
Use the result to simplify the setup. A skill containing ordinary instructions should not require an extra polling process merely to remain discoverable. A connection that is deliberately shared across conversations should have a clear lifecycle rather than one forgotten copy per abandoned chat. A hook should perform the bounded check associated with its event, not rescan every unrelated project. When you cannot attribute the cost, retain the observation as unresolved and collect a second controlled sample. Disabling random processes may hide the symptom while also removing the very capability the user expected to have.