Suppose your team has a skill that drafts migration notes when a pull request changes a public API. It reads the diff, looks for callers that use the old API, and writes a before-and-after example. The first step in the skill says to call repo_search. When you install the same skill in another coding agent, that tool may have a different name, or the agent may only have access to the files in its current checkout.
AAIF welcomed Agent Skills in October as an open standard for sharing reusable instructions and supporting files across agents, and our introduction to Agent Skills covers the basics. A shared format lets another agent read the same skill. Using it still depends on what that agent can find and access.
Write down what the job needs
The Agent Skills specification defines a skill as a directory containing a SKILL.md file. The file starts with YAML frontmatter, including the required name and description, followed by the instructions in Markdown. The directory name matches the name field. For this example, save the file as api-migration-note/SKILL.md.
---
name: api-migration-note
description: >-
Drafts a migration note when a pull request changes or removes a public API.
Use for breaking changes, deprecations, renamed functions, changed signatures,
or requests to identify who needs to update their code.
---
Read the diff and identify the public API that changed.
Search the available repository files for callers of the old API.
Draft a note that explains what broke, who needs to update their code,
and shows a before-and-after example based on the change.
If the diff or any relevant callers are inaccessible, say what you
could verify and what remains unchecked.Under the spec’s progressive disclosure model, agents load each skill’s name and description at startup and read the body when the skill is activated. Terms such as “changed signatures” help an agent recognize when to select the skill automatically. The body tells it what evidence to collect and what the reader should get back. In this case, the agent needs the diff and access to the relevant repository files.
Replace the tool name with the evidence you need
Suppose the original skill says:
Call `repo_search` for the old API name and open the matching callers.A version that can work with different search tools could say:
Search the available repository files for references to the old API.
Open the matching files and confirm which references are callers.The second instruction specifies the evidence to find and leaves the choice of search tool to the agent. A text match could be a call, a comment, or a mention in documentation, so it still asks the agent to inspect the files. It also makes the search scope visible. If the workspace only contains the library itself, the agent may be able to show what changed without knowing which downstream projects use it.
Some dependencies belong in the skill. A procedure that relies on a particular command-line utility or access to a specific service can document that requirement in the optional compatibility field. If the skill ships a template or reference file, use a path relative to the skill directory. The same tool-name dependency can show up in frontmatter. The spec’s experimental allowed-tools field can list entries such as Bash(git:*) Bash(jq:*) Read. If the receiving agent uses different tool names or handles the field differently, check which tools are actually available under its permissions.
Check how the receiving agent handles the skill
The receiving agent has to find the skill before it can use the instructions. Check where that agent looks for skills and place the whole directory there, including any bundled files. In a Google Open Source Blog post, Kurtis Van Gent identifies discovery, naming conflicts, bundling, and conformance differences as areas for further work. He also calls for a portable way for skill authors and agent hosts to declare which version of the spec they support.
Before moving the skill, check its frontmatter and directory naming with the reference validator. With skills-ref installed, run this from the parent directory.
skills-ref validate ./api-migration-noteThe validator checks the file format and naming rules. Use the receiving agent to check whether it can load the skill and carry out the procedure.
Use the same pull request and task prompt when checking the skill in the next agent. Keep the checks small enough to see which part of the move needs work.
- Discovery. Ask for a migration note for the API change. Check whether the agent loads the skill. If it can load the skill when named explicitly, check automatic selection separately.
- Access. Check whether the agent can inspect the diff and open at least one caller you know exists in the checkout. If the skill bundles files or requires a utility, check that the files are present and the agent has permission to use the utility. If it cannot reach part of the code, check whether the note makes that gap clear.
- Output. Check that the note names the breaking change, identifies who needs to update their code, and gives a before-and-after example that matches the diff. Two agents can phrase the note differently and still meet those criteria.
If the second agent produces a plausible note while missing a known caller, you have a concrete place to investigate. Check which files it could see and whether the skill told it to open and verify search matches. Those checks give you a way to improve the same skill before you share it with another team.
Share
Author




