How to Create Portable Skills for AI Agents

A useful skill is more than a prompt saved in a folder. It is a small, reproducible engineering process: a clear trigger, explicit inputs, bounded permissions, host adapters, verification steps, and a predictable handoff. This article shows how to package that process so it can move between AI agents without pretending that every host has the same tools or security model.
The central problem is easy to state and difficult to solve: how do you describe a repeatable engineering process once, then run it across different agents while preserving the context, tools, and permissions supplied by each host?
The answer is to separate the process from its environment. The process defines what must happen and how success is checked. The environment supplies the available model, filesystem, tools, credentials, approval rules, and runtime conventions. Portability comes from making that boundary explicit.
What “portable” means
In this guide, a skill is a documented procedure that an agent can apply when a task matches its purpose. A portable skill does not require identical agents. It requires that different hosts can interpret the same contract and provide their own implementation details.
Portability therefore has three levels:
- Text portability: the instructions can be read without relying on one vendor’s hidden terminology.
- Operational portability: the host can map required actions to its own tools and permission model.
- Outcome portability: equivalent inputs produce artifacts that satisfy the same acceptance criteria.
A skill can be text-portable but not operationally portable. For example, “inspect the repository” is understandable everywhere, but one host may expose a shell while another only exposes a repository browser. The portable contract should describe the intent and the evidence required; the host adapter should describe how to obtain that evidence.
A concrete case: a repository review skill
Consider a skill called repository-review. Its job is to inspect a codebase, identify relevant files, analyze an implementation against a stated requirement, and report findings with file references. It should not modify files unless the caller explicitly requests a fix.
The same process may run in three environments:
- an agent with shell access and a local checkout;
- an agent with read-only repository tools;
- an agent that can inspect uploaded files but cannot access a network or external service.
The review logic is the same. Discovery, evidence collection, analysis, and reporting remain stable. The available search command, repository location, and approval flow vary by host.
The portable skill contract
Start with a short contract before writing detailed instructions. The contract should answer six questions:
- When should the skill activate?
- What inputs must be present?
- What context may it read?
- What actions may it perform?
- What evidence must it produce?
- What should it do when a requirement cannot be verified?
A useful contract is specific enough to test but abstract enough to survive a change of host. For the repository-review example:
name: repository-review
purpose: Review an implementation against an explicit requirement.
activation:
- the user asks for diagnosis, review, or verification
required_inputs:
- requirement or review question
- repository or file scope
read_actions:
- list files
- read relevant files
- inspect available tests and configuration
write_actions: none unless explicitly authorized
output:
- findings ordered by severity
- evidence with file paths and relevant locations
- unverified assumptions and missing access
- concise conclusion
failure_policy:
- never convert unavailable evidence into a claim
Notice what this contract does not contain: a vendor-specific command, a secret, a hard-coded workspace path, or an assumption that every host has the same approval mechanism.
Recommended directory structure
Keep the portable core small. Put host-specific material in adapters or deployment notes rather than mixing it into the procedure.
repository-review/
├── SKILL.md
├── references/
│ ├── review-checklist.md
│ └── evidence-format.md
├── examples/
│ ├── request.md
│ └── report.md
├── adapters/
│ ├── shell.md
│ ├── readonly-repository.md
│ └── uploaded-files.md
└── tests/
├── cases.md
└── expected-behavior.md
SKILL.md is the entry point. It should explain purpose,
activation conditions, inputs, procedure, boundaries, and output format.
References contain detail that is useful during execution but not
necessary in every invocation. Examples show shape, not guaranteed
results. Adapters map abstract actions to host capabilities.
Writing the core instructions
Write the core as a sequence of observable stages. Avoid instructions such as “be careful” or “use your best judgment” unless you also define what careful behavior looks like.
# Repository Review
## Purpose
Review a specified implementation against a stated requirement and return
evidence-bounded findings. This skill is read-only by default.
## Before starting
Confirm:
- the review question is explicit;
- the file or repository scope is known;
- the host's available read and search capabilities are known.
If a required input is missing, ask for it before analyzing.
## Procedure
1. Restate the review question in one sentence.
2. Discover the scoped files using the host's available read/search mechanism.
3. Read the smallest set of files that can answer the question.
4. Trace relevant data or control flow.
5. Compare observed behavior with the requirement.
6. Record each finding with:
- severity;
- claim;
- evidence;
- impact;
- recommended next action.
7. List assumptions and checks that could not be performed.
8. Separate verified observations from suggestions.
## Boundaries
- Do not edit, delete, commit, or publish files unless explicitly authorized.
- Do not expose secrets or personal data in the report.
- Do not claim that a test, build, or command ran unless its output was observed.
## Output
Return:
- scope;
- findings;
- evidence;
- limitations;
- conclusion.
This structure is deliberately procedural. Each step creates an intermediate artifact or decision that can be checked. That makes the skill easier to debug when two hosts produce different results.
Preserving host-specific context
Host context should be injected, not assumed. A host can provide a small runtime block before the skill runs:
runtime:
workspace: /workspace/project
readable_tools:
- file_list
- file_read
- text_search
writable_tools: []
network: disabled
approval_required_for:
- file_write
- external_message
available_tests:
- project-defined commands only
This is an illustrative configuration, not a universal standard. Its value is the explicit distinction between capability and permission. A tool may exist but still be unavailable for this task. A command may be documented but not executable in the current environment.
The skill should use the runtime block to make decisions:
- If search is available, use it to narrow the reading scope.
- If only file reads are available, state that discovery was limited.
- If writes require approval, stop before proposing an implicit edit.
- If network access is disabled, do not imply that external sources were checked.
Avoid embedding credentials, absolute personal paths, machine-specific usernames, or undocumented environment variables. If a secret is required, name the required capability without reproducing the secret: “the host must provide authenticated access to the repository.”
Designing adapters
An adapter translates the portable action into a host-specific action. It should be short and mechanical. For example:
## Shell adapter
Portable action: discover files in the review scope.
Preferred operation:
- use `rg --files` from the repository root;
- narrow results with an explicit path or file pattern;
- record the scope used.
Fallback:
- use the host's file listing tool;
- if recursive discovery is unavailable, ask for a narrower scope.
Evidence:
- include the discovered paths in the working notes;
- do not report a file as inspected unless it was actually read.
The adapter should not redefine the review method. If one adapter starts adding a different severity model, output schema, or decision rule, it has become a fork of the skill rather than a host integration.
Permissions are part of the interface
A portable skill must declare side effects explicitly. “Read-only by default” is useful, but a stronger interface names each class of action:
| Action | Default | Required handling |
|---|---|---|
| Read scoped files | Allowed | Stay within the declared scope. |
| Search text | Allowed when available | Report the search mechanism if it affects coverage. |
| Run tests or builds | Conditional | Run only when the host and request authorize it; record observed output. |
| Write files | Not allowed | Request explicit authorization before writing. |
| Send external messages | Not allowed | Require a separate approval and destination. |
This table is not merely documentation. It is a testable boundary. A host can verify that a read-only invocation does not call a write tool, while a reviewer can identify whether a requested action exceeds the skill’s contract.
Verification without invented evidence
The most important portability rule is evidence discipline. The skill must distinguish among:
- Observed: directly read or produced during the current run.
- Reported: supplied by the user or another system but not independently checked.
- Inferred: a reasoned conclusion based on observed evidence.
- Unavailable: a check the host could not perform.
A portable report can use a compact evidence record:
finding:
severity: medium
status: observed
claim: "The handler accepts an unvalidated identifier."
evidence:
- path: src/handlers/orders.ts
location: "createOrder"
observation: "The input is passed to the service without schema validation."
impact: "Malformed input may reach the service layer."
next_action: "Confirm the intended validation boundary and add a focused test."
If the host could not run the test suite, the report should say exactly that. “No failing tests found” and “tests were not run” are different statements and must never be merged.
A reproducible portability test plan
Test the skill as a process, not only as a text file. Use the same fixture repository and the same review question across environments. Keep the fixture synthetic and free of credentials or personal data.
1. Define the fixture
Create a small repository containing a known issue, a relevant test, an irrelevant directory, and a configuration file. Write down the expected findings before running the skill. The expected result is the oracle for comparison; it is not a claim about any production codebase.
2. Define the invariant output
Compare stable fields rather than raw wording:
- the requested scope was respected;
- the known issue was identified;
- the finding includes evidence;
- unavailable checks were disclosed;
- no unauthorized write or external action occurred.
3. Run capability variants
At minimum, test:
- full read and search access;
- read-only access without shell execution;
- limited file access with an intentionally incomplete scope;
- a host where a requested test command is unavailable.
Each run should record the host capabilities, inputs, actions requested, output, and limitations. Do not compare a host with network access to a host without network access as if they had identical evidence.
4. Check side effects
Before and after each run, inspect the fixture for unexpected changes. For a read-only skill, the expected result is no file modification. If the host exposes tool-call logs, inspect those logs for write, delete, commit, upload, or messaging actions.
5. Compare results
Portability does not mean identical prose. It means equivalent decisions under equivalent evidence. Differences should be classified:
- Acceptable variation: different commands, formatting, or ordering.
- Coverage variation: one host could inspect less because it had fewer capabilities.
- Semantic drift: hosts disagree about the finding despite equivalent evidence.
- Boundary violation: a host performs an unauthorized side effect.
Useful commands for a local fixture
The following commands are examples for a Unix-like shell. They are not evidence that they were run for this article, and a host may provide different tools.
# Discover files without printing file contents
rg --files ./fixture
# Search for the fixture marker
rg -n "TODO|validate|AUTH" ./fixture
# Inspect repository changes after a read-only run
git -C ./fixture status --short
# Record a file checksum before and after an authorized test
sha256sum ./fixture/src/example.ts
A Windows host, a web interface, or a restricted agent may need a different implementation. The test plan remains valid if the adapter records equivalent evidence.
Common failure cases
Hidden host assumptions
A skill says “open the repository root,” but the host provides only uploaded files. Fix this by making the scope an explicit input and defining a fallback when root discovery is unavailable.
Tool-name coupling
A skill instructs the agent to call a particular tool name. This breaks as soon as another host uses a different interface. Describe the capability first—search, read, execute, write—and map it in an adapter.
Permission leakage
A review skill silently edits a configuration file while “testing” a hypothesis. Make writes a separate phase requiring explicit approval. If a fix is useful, return a patch proposal or a follow-up plan.
Over-broad context
Reading an entire repository can expose unrelated secrets and make the result less reproducible. Start with the smallest scope that can answer the question, then expand only when evidence shows that more context is needed.
False portability
Two hosts produce similar prose, but one could not perform the required checks. Compare evidence and limitations, not tone. A shorter report with explicit uncertainty is more portable than a confident report built on unavailable context.
Limitations
A portable skill cannot remove differences in model behavior, tool quality, filesystem semantics, isolation, or approval policy. It also cannot guarantee that two hosts interpret ambiguous natural language in the same way. These differences must be reduced with explicit inputs, structured outputs, fixtures, and acceptance criteria.
Portability is also relative to a capability envelope. If a task requires compilation, a host that cannot execute a compiler can still run the skill, but only in a limited mode. The correct result is a disclosed limitation—not an invented build result.
A practical checklist
- Does the skill have one clear purpose and activation condition?
- Are required inputs and scope explicit?
- Are abstract capabilities separated from host-specific tool names?
- Are reads, writes, execution, network access, and external messages bounded?
- Does the output distinguish observed, reported, inferred, and unavailable evidence?
- Can the skill run in a reduced-capability mode?
- Is there a synthetic fixture with expected behavior?
- Are side effects checked after each run?
- Are differences between hosts classified rather than hidden?
- Does the skill avoid secrets, personal data, and undocumented assumptions?
Conclusion
The reusable unit is not a universal command sequence. It is a stable process contract surrounded by explicit host adapters. Define the invariant work, declare the required evidence, keep permissions visible, and test the same fixture under different capabilities. That is enough to make a skill transferable without pretending that environments are identical.
For related implementation patterns, continue with the guides or look up unfamiliar terms in the glossary.