Engineering guide · 25 min read ·

How to Create Portable Skills for AI Agents

Как создавать переносимые навыки для AI-агентов
Temporary fallback cover; replace in editorial pass.

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:

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:

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:

  1. When should the skill activate?
  2. What inputs must be present?
  3. What context may it read?
  4. What actions may it perform?
  5. What evidence must it produce?
  6. 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:

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:

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:

3. Run capability variants

At minimum, test:

  1. full read and search access;
  2. read-only access without shell execution;
  3. limited file access with an intentionally incomplete scope;
  4. 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:

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

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.

We publish what works for us—and implement the same solutions for your business. We design AI automation, Telegram bots, chats, and AI agents for real-world processes. Discuss your project →