An agent skill may look harmless: a folder of instructions, examples, a script, and a list of tools. In production, it has more influence. It tells an agent how to interpret work, seek evidence, select tools, and sometimes propose or take actions. That makes a skill part operating procedure, part integration contract, and part executable supply chain.
On this page
- What an agent skill actually is
- Why skills have become a production security concern
- Treat a skill as a governable unit of capability
- Separate skill instructions from authority
- A practical skill manifest
- Test skills before they reach production
- Example: a safe internal service-request skill
- Operating skills after launch
- Frequently asked questions
What an agent skill actually is
An agent skill is a reusable package of workflow guidance for a defined job. Depending on the runtime, it may contain natural-language instructions, templates, examples, data-handling rules, scripts, tool references, or UI components. Its purpose is to give an agent a reliable starting point for work it performs repeatedly.
That description can make a skill sound like documentation. In practice, it has more influence than ordinary documentation because it is supplied to a system that can select tools, retrieve records, and propose or initiate actions. If a skill says "resolve this request by updating the customer record," it is shaping an operational path - not merely explaining a process to a person.
It helps to distinguish three layers:
- The model supplies language, reasoning, and tool-selection capability.
- The skill supplies task-specific workflow knowledge and boundaries.
- The integration layer supplies permitted access to systems and data.
A secure design does not let any one layer stand in for the others. A skill can say what a workflow should attempt; it must not be the thing that grants authority to do it.
Why skills have become a production security concern
Reusable skills are becoming a recognised attack and governance surface because they sit between broadly capable models and real systems. OWASP's Agentic Skills Top 10 calls out risks in this intermediate behaviour layer, including malicious instructions, insecure dependencies, and excessive permissions.
The issue is not limited to intentionally malicious content. A well-meaning skill can still create a production problem when it:
- instructs the agent to call a tool more broadly than the business process requires;
- contains old policy, examples, or endpoint assumptions;
- pulls scripts or templates from a mutable location;
- embeds credentials, API keys, or sensitive routing details;
- treats documents retrieved during work as trusted instructions;
- changes its behaviour without a versioned review trail.
This matters more as organisations adopt Model Context Protocol servers and other standard tool interfaces. MCP makes a tool contract easier to expose and reuse. It does not decide whether a skill should use that tool, whether a given user is authorised, or whether an outward action needs review.
A useful rule is simple: if changing a skill could change what an agent reads, proposes, calls, or executes, that change belongs in your production change process.
Treat a skill as a governable unit of capability
A skill should have an owner, a purpose, an approved release version, and a defined operating boundary. "The agent can use it" is not enough of a description.
Start by writing a capability statement that is narrow enough to test. For example:
Draft a service-request resolution from approved internal knowledge, then submit the draft for review. Do not alter the request, change ownership, or contact the requester.
That statement tells engineers, reviewers, and operators what success looks like. It also makes non-goals visible. A skill designed to prepare a draft should not quietly acquire a tool that closes tickets.
For each skill, record:
- the business purpose and expected user;
- systems and data categories it may access;
- tools it may request, including read versus write operations;
- the authority required for any consequential action;
- escalation conditions and prohibited actions;
- its owner, version, review record, and retirement date if applicable.
This is the same discipline CodeDTX recommends when retrofitting agents into legacy systems: expose a small, governable interface around the work that matters instead of giving an agent a broad credential and asking it to be careful.
Separate skill instructions from authority
Instructions can guide an agent. They cannot establish who the agent is acting for, which record the user may access, or whether a write is permitted.
Keep those decisions in trusted application and integration code. The application should derive user and organisation context from an authenticated session, request appropriately scoped access through a supported delegation path, and enforce authorisation again at the destination system. The agent should never generate its own role, scope, or approval state.
For skills with outward effects, use CodeDTX's Propose–Decide–Execute pattern:
- The skill helps the agent gather permitted evidence and prepare a versioned proposal.
- A named person or policy-controlled decision service evaluates that exact proposal.
- A separate executor applies only the approved operation and records the destination result.
This prevents an instruction such as "make the update now" from becoming the final authority for an irreversible action. It also makes later investigation possible: the organisation can distinguish the request, the proposal, the decision, the execution attempt, and the resulting record.
For a deeper treatment of identity and delegated access, see How do you handle authentication for an agent acting on a user's behalf?.
A practical skill manifest
A manifest gives a skill an inspectable contract. Its exact syntax will vary, but the policy information should be explicit and machine-checkable where possible.
name: service-request-draft
version: 1.4.0
owner: operations-platform
purpose: Draft evidence-backed resolutions for internal service requests.
allowed_tools:
- knowledge.search
- service_requests.get
- proposals.create
denied_tools:
- service_requests.update
- email.send
- identity.admin
data_rules:
allowed_classifications:
- internal
redact_before_proposal:
- access_tokens
- payment_details
execution:
mode: propose_only
requires_human_approval: true
approval_scope: proposal_hash
limits:
max_tool_calls: 8
max_records_per_run: 5
stop_when:
- source_conflict
- missing_required_evidence
- request_outside_supported_scope
The manifest should be reviewed alongside the skill content, not treated as decorative metadata. A pull request that adds a new tool, expands a data classification, or changes propose_only to direct execution is a material capability change.
Where a runtime cannot enforce every field directly, enforce the most important controls in the tool gateway and execution service. A declared denied_tools list is useful; a server-side policy that refuses the call is the actual boundary.
Test skills before they reach production
Testing a skill is not just asking whether the output sounds polished. The skill should be evaluated as a workflow component with a known boundary.
Build a small, representative test set that covers the work it is intended to perform. Then add negative and adversarial cases:
- a request that needs unavailable or restricted data;
- retrieved content containing instructions to ignore the skill's constraints;
- conflicting source records;
- a tool result with malformed or incomplete data;
- a request that appears routine but requires a prohibited write;
- an expired approval or a proposal changed after approval;
- a dependency or template version that no longer matches the skill.
The expected outcome may be a useful proposal, a request for human input, or a controlled refusal. It should not always be "the agent completed the task." A good skill knows when it lacks evidence or authority.
Capture the skill version, model configuration, tool-contract version, and evaluation result together. This makes a regression explainable when a later update changes behaviour. The guide to what AI agent evals catch explains why evaluation must test the entire workflow rather than only the model response.
Example: a safe internal service-request skill
Imagine an operations team wants an agent to help resolve access requests. A fast but unsafe design gives the agent a broad administration tool and a skill that says, "Grant the requested access after checking the ticket."
A production-ready design is narrower:
- The skill can read the request, relevant policy, and the requester's permitted organisational context.
- It can produce a proposal identifying the requested access, supporting evidence, and any missing information.
- It cannot grant access, edit identity records, or message the requester directly.
- A reviewer approves or rejects the exact proposal.
- A separate executor validates that approval, checks current policy and target state, performs the change through a scoped integration, and records the outcome.
This design handles ordinary requests efficiently while making exceptional cases visible. If the policy is ambiguous or the request concerns a privileged system, the skill should stop and route the case to an authorised reviewer. That is not a failure of automation; it is an explicit product decision about where discretion belongs.
Operating skills after launch
Skills need production ownership just as APIs, services, and policies do. Monitor both operational health and behavioural boundaries.
At minimum, retain enough evidence to answer:
- Which skill version ran for this request?
- Which tools did it request, and which calls were allowed or refused?
- What sources supported the proposal?
- Did a decision approve the exact version that reached execution?
- What did the destination system confirm?
- Did the skill hit a stop condition, a policy failure, or an unexpected dependency change?
Do not automatically retain every prompt and response forever. Store the minimum useful evidence subject to data classification, retention, and access rules. A trace reference, source revision, structured proposal, decision record, and executor result are often more useful - and safer - than an indiscriminate transcript archive.
Review skills on a schedule and after any material change to their tools, dependencies, source content, or policy. A formerly safe skill can become unsafe when a connected system adds a more powerful operation or when a dependency starts returning different content.
The operational patterns in How do you monitor an AI agent in production? and How do you audit what an AI agent did? apply directly here: connect requests to evidence, decisions, execution, and verified outcomes.
Agent skills are a powerful way to make agentic systems useful across real business workflows. But reuse without control simply moves risk into a folder that is easy to overlook. Treat each skill as a versioned capability with a narrow purpose, enforced access, tested failure modes, and an observable operating record.
If you are deciding how to introduce skills, MCP tools, or reusable agent workflows into a production environment, talk to CodeDTX about designing the boundaries before capability becomes dependency.
Frequently asked questions
Are agent skills just prompts?
No. A simple skill may be mostly instructions, but a production skill often bundles examples, scripts, tool expectations, data rules, and workflow decisions. Because it influences how an agent reaches external systems, it deserves more review than an ad hoc chat prompt.
Should every skill require human approval?
No. Approval should match the consequence of the action. A read-only skill that summarises permitted internal material may not need a human decision on each run. A skill that can change a customer record, provision access, send an external message, or affect a financial process should have an explicit decision and execution boundary.
Can a skill safely call MCP tools?
Yes, provided MCP is treated as an integration layer rather than an authorisation layer. Limit the tools exposed to the skill, enforce permissions in the resource system, treat tool results as untrusted input, and keep consequential writes behind a separate execution control.
How do we prevent a skill from following malicious instructions in retrieved content?
Treat retrieved content as data, never as authority. Define a clear instruction hierarchy, label untrusted material, validate tool outputs, and require the workflow to stop when retrieved content asks it to change its own rules, disclose protected information, or use tools outside its declared purpose. Test these cases before release.
Who should own a production skill?
Ownership is shared but explicit. A business owner defines the intended workflow and acceptance conditions; an engineering owner maintains the implementation and integrations; security and compliance reviewers assess relevant controls; an operational owner handles incidents and change management. One named accountable owner should coordinate changes and retirement.
