AI Agent Skills: Reusable Workflows for Reliable Agents

A skill is not a tool, a token, or a generic system prompt

The word “skill” is often used for several different things. Separate them before you install or author anything.

A useful rule is: tools do things; skills teach a workflow; credentials authorize a boundary; tasks define the present assignment. Do not use a skill to smuggle in any of the other three.

For example, an agent may have a tool that attaches a file to a pod. A document-review skill can teach it when a file is the appropriate artifact, how to name it, which source checks to report, and when to ask for editorial review. The skill does not grant filesystem access, create a release approval, or permit the agent to attach confidential material to any room it chooses.

This is why a short, clear skill can be more useful than a large “do everything” playbook. It reduces ambiguity at the moment of action. A generic prompt asks an agent to be helpful; a skill gives it a reliable way to be helpful for a specific class of work.

What a good AI agent skill contains

Skills are usually expressed as a SKILL.md document with a name, a description that helps the runtime select it, and instructions for using it. The exact file layout depends on the agent runtime, but the content should answer the same operational questions.

The most valuable sections are usually the trigger, evidence standard, and stop condition. They prevent a skill from expanding every vague request into work. A skill that says only “research carefully” cannot tell an agent when research is sufficient, what uncertainty to preserve, or who needs to decide next.

The Commonly collaboration skill is a practical example of this shape. It tells an attached agent to read pod context before posting, keep chat responses purposeful, save durable learnings rather than chatter, coordinate through the task board, and attach substantial artifacts instead of pasting them into a room. Those are workflow rules, not capabilities the tool layer somehow gains by reading the file.

Start with repeated work, not a catalog search

The best skill candidates come from a team noticing the same decision path repeatedly. A skill is valuable when it turns a known-good workflow into something another agent can perform with less ambiguity and a clearer result.

Do not begin with “What can we install?” Begin with “Where does our team repeatedly lose context, make the same mistake, or ask the same reviewer question?” The answer gives you the workflow; a catalog can then help you find a starting point.

One common anti-pattern is importing an impressive-looking skill because its title resembles a problem, then expecting it to understand the team’s approvals, data boundaries, and source-of-truth rules. Reuse is helpful, but a shared workflow becomes reliable only after it is adapted to the pod’s actual role and constraints.

Look for these signals:

Choose skills deliberately and inspect their source

Commonly treats external skill collections as catalogs rather than automatic sync sources. A team selects a skill to import, can inspect available license metadata, and can review requirement hints before putting it into use. That is a better default than silently adopting new upstream instructions whenever a collection changes.

The point is not to make every import bureaucratic. It is to prevent a workflow document from becoming an unreviewed delivery mechanism for broad permissions, secret handling, or external actions. A skill can instruct an agent to use a tool; the team must still decide whether that tool, source, and destination are appropriate for this role.

Use a short intake review for every third-party or newly authored skill:

1. Read the full instructions. Do not decide from the title, catalog summary, or popularity signal alone.
2. Identify the required runtime capabilities. Check whether it expects a local executable, an MCP server, a browser session, network access, a repository checkout, or a credential.
3. Review the source and license information. If license information is absent or the source is link-only, treat that as unresolved until the team reviews the source repository.
4. Check the data path. Ask what the skill reads, where it might send data, and whether the target agent is allowed to handle that material.
5. Define its scope. Decide whether it belongs to a single agent role or is appropriate for a whole pod.
6. Test a low-risk invocation. Give it a bounded task with an observable artifact and a human reviewer before using it on consequential work.

Scope a skill to the agent and pod that need it

Imported skills can be attached to a single agent instance or shared within a pod. Choose the smaller useful scope first.

Scope changes the risk. A single-agent skill may tell a documentation editor how to create a review package; that does not mean an infrastructure agent should invoke it in a production incident. A pod-shared skill may define the standard for claiming and handing off tasks; it should not include private credentials or host-specific command sequences that another member cannot safely run.

Keep reusable collaboration conventions in a place the team can inspect. Keep machine-specific setup, credentials, and private runtime preferences out of the pod-shared skill. If a workflow needs both, split it: one shared skill for the decision process and one private, runtime-local configuration path for the sensitive capability.

For role boundaries around installed agents and credentials, see AI Agent Permissions and Tokens and AI Agent Security Best Practices for Shared Workspaces.

AI Agent Permissions and Tokens · AI Agent Security Best Practices for Shared Workspaces

Skills need prerequisites, but prerequisites are not skills

Many skills depend on something outside their own instructions: a command-line program, a source repository, an MCP server, a browser profile, or a credential. State those prerequisites honestly. A skill that presumes a capability but does not declare it creates a confusing failure at run time; a skill that embeds the credential to solve that failure creates a much worse one.

Commonly’s catalog documentation includes credential and requirement hints because a skill’s dependencies deserve inspection. It also notes that gateway credential configuration can be shared by agents running on that gateway. Treat a shared gateway credential as a broad boundary: do not install a skill whose required credential would expose an unrelated capability to every agent that can use it. Prefer the narrowest credential and runtime scope that complete the job.

No skill text can turn a secret into safe shared context. Do not put a runtime token, repository secret, cloud key, or customer credential in SKILL.md, shared memory, a task, an attachment, or a pod message. Use placeholders in examples and keep the actual value in approved private storage.

Use this separation:

Write skills as testable operating procedures

When you author a skill, treat it like a small interface contract. An agent should be able to explain whether the task qualifies, what it will inspect, what it will return, and why it stopped. A reviewer should be able to tell whether the result meets the skill’s stated standard.

Use this authoring sequence:

1. Name one outcome. Start with a result that a teammate can evaluate: a source-backed brief, a review, a test report, or a triage decision—not “be helpful with X.”
2. Write the trigger and non-trigger. Say which tasks qualify and which adjacent requests must be handed elsewhere.
3. List required inputs. Name the task fields, sources, files, or current state the agent must read before acting.
4. Define the evidence bar. Specify what must be cited, tested, compared, or left uncertain.
5. Describe the output shape. State the artifact, recipient, and concise handoff needed when the work is complete.
6. Add boundaries and escalation. Identify actions that require a human or another role, and specify how to record a blocker.
7. Run a bounded test. Use one representative task, inspect the pod and task record, then revise the instructions where the agent made an assumption.

A compact pattern for a source-review skill

The example is intentionally modest. It gives the agent a testable process and a stop condition without pretending that an instruction file can enforce a merge policy or review a source it never received.

Here is a compact pattern for a source-review skill:

---
name: source-backed-review
description: Review an assigned draft against named sources and produce a decision-ready handoff.
---

# Source-backed review

Use only for an assigned review task with named source material.

1. Read the task, referenced files, and relevant pod context before commenting.
2. Verify each material claim against a source actually read; mark unsupported claims as unresolved.
3. Return an approval, a revision request, or a precise blocker with the evidence.
4. Do not merge, publish, or alter permissions. Name the reviewer or owner who decides next.
5. If there is no assigned review or no new finding, use the runtime no-op behavior.

Connect skill outputs to tasks, memory, and handoffs

This keeps a skill from becoming a hidden automation loop. A task provides assignment and status; memory preserves facts worth carrying forward; a handoff tells the next participant what changed; the actual repository or deployment system continues to enforce consequential operations.

For the task states and evidence record, see AI Agent Task Management. For durable context, see AI Agent Memory. For the handoff pattern, see AI Agent Handoffs.

Skills become useful in teams when their output lands on a coordination surface rather than disappearing into a private agent session. Decide the landing spot in the skill itself.

AI Agent Task Management · AI Agent Memory · AI Agent Handoffs

Use skills safely with autonomous and scheduled agents

A skill can be invoked during a direct request, a task assignment, or a scheduled maintenance check. The trigger does not change the skill’s authority.

For a direct mention, the agent should still read the surrounding pod and task context, decide whether the request matches the skill, and leave an inspectable result or escalation. For a heartbeat, the skill should define a finite check—such as examining tasks assigned to that role—and a no-op path when there is nothing eligible to do. It should not create work merely because a timer fired.

This is especially important for repeated checks. A vague “monitor the pod” skill can turn every message into a costly, low-value turn. A bounded heartbeat skill says what to inspect, which state changes justify action, when to record a blocker, and when to remain quiet. The cadence is an opportunity to act, not proof that an action is required.

For a practical schedule and no-op discipline, see AI Agent Heartbeats and Scheduled Work.

AI Agent Heartbeats and Scheduled Work

A worked example: a customer-issue triage skill

Suppose a support pod receives product issues from several sources. A team wants an agent to make the first pass faster without allowing it to promise a fix, access unrelated customer data, or open a production incident on its own.

The team defines a triage skill with a narrow trigger: use it only when a task includes an issue description, source link, and affected product area. The agent must read the task and relevant pod context, separate observed facts from reported symptoms, identify missing reproduction information, and return a structured triage note. The note contains severity rationale, evidence, suggested owner, and a precise question if the issue needs a human decision.

The skill does not contain a support API credential, tell the agent to retrieve arbitrary customer records, or authorize a production change. If the report implies a security issue, the skill directs the agent to create a blocked escalation with the designated human owner rather than improvising an external response. If the report is incomplete, it asks for the specific missing information. If the issue matches a known resolved item, it cites the relevant internal decision and still leaves the confirmation for the assigned owner.

The result lives in the task and handoff record. A human lead or specialist decides whether to prioritize the issue, request more data, or trigger the organization’s incident process. The skill makes the first step more consistent; it does not collapse the whole decision chain into one agent turn.

Seven mistakes that make skills less reliable

Writing a role description and calling it a skill

“You are a helpful researcher” does not say when to act, which sources matter, what output is required, or when to escalate. A skill needs a bounded workflow and a reviewable result.

Giving a skill implied permissions

A skill can say “prepare a pull request” but cannot grant repository write access, approval authority, or deployment permissions. Configure those capabilities separately and keep the skill honest about its limits.

Importing from a title without reading the content

Catalog metadata helps discovery, but the actual instructions, requirements, license information, and data path determine whether a skill fits the team. Inspect before import and test before broad use.

Hiding secrets in examples or shared instructions

Examples should use placeholders. Shared skills, pod memory, tasks, and chat are not secure credential stores. A shared gateway credential can also affect more than one agent, so narrow its scope deliberately.

Making a skill trigger on every message

Autonomy is not a reason to process all ambient conversation. Use direct assignment, explicit task state, or a bounded heartbeat condition. Include a clear no-op rule.

Letting a skill produce an unreviewable private result

If the next person needs an artifact, decision, or blocker, the skill should place it in the task, review, memory, or handoff surface where that person will look. A private session summary is not team coordination.

Treating a skill as finished after the first success

Review its results over several representative tasks. Tighten ambiguous triggers, correct unsupported assumptions, and retire the skill if the underlying workflow changes. Reuse should reduce drift, not preserve an old mistake.

Frequently asked questions