Build Once, Run on Any Agent: A Practical Guide to Agent Skills
By Andrea Griffiths, Senior Developer Advocate at GitHub (@AndreaGriffiths11)
About the Author
Andrea Griffiths is a Senior Developer Advocate at GitHub with over a decade of experience in developer tools. She pairs technical depth with a mission to make advanced technologies more accessible. After transitioning from Army service and construction management into software development, she brings a unique perspective to bridging complex engineering concepts and practical implementation. She lives in Florida with her Welsh partner, two sons, and two dogs, where she continues to drive innovation and support open source through GitHub's global initiatives. Find her online at @acolombiadev.
Why Portability Matters in the Agent Era
The AI agent landscape in 2026 looks nothing like it did even a year ago. Most developer teams now orchestrate multiple agents from different vendors—Claude, GPT-based assistants, open-weight models running locally, and a growing ecosystem of MCP-connected tools. The painful reality: capabilities you build for one agent rarely transfer cleanly to another. Teams end up rebuilding the same logic three or four times.
This guide walks through a practical pattern for building portable agent skills—capabilities you define once and run across any agent runtime.
What Is an Agent Skill?
A skill is a self-contained, declaratively described capability that an agent can discover and invoke. Think of it as the agent equivalent of a well-scoped CLI tool: it has a name, a description, an input/output contract, and an implementation. When built correctly, the skill doesn't care whose model is on the other side of the conversation.
The Portability Stack
Three layers make cross-agent skills work in practice:
- A vendor-neutral schema. Describe each skill with a JSON or YAML manifest covering identity, parameters, and expected outputs. The 2026 ecosystem has largely converged on MCP-compatible tool definitions, which gives you a mature foundation.
- A thin adapter per runtime. Each agent framework exposes tools slightly differently. Keep adapters small and mechanical—they should translate, not add logic.
- A shared execution layer. The actual business logic lives once, behind a stable interface that adapters call into.
- Over-specifying parameters. If your contract assumes a specific model's tool-calling quirks, portability dies.
- Hiding logic in adapters. Adapters should translate, not think. The moment you add behavior there, you've fractured your skill.
- Skipping the harness. The whole point is cross-agent consistency—test for it.
- Ignoring authentication and rate limits. Each runtime handles credentials differently; design for it up front.
Step-by-Step: Building Your First Portable Skill
1. Define the contract
Start with the manifest. Specify what the skill does, what parameters it accepts, and exactly what it returns. Ambiguity here is the number one source of failures across runtimes.
2. Implement once
Write the logic in a language-agnostic way—often a small service or a library function with a clean boundary. Avoid leaking framework-specific types into this layer.
3. Wrap per runtime
For each agent platform you support, write a minimal adapter. In most 2026 frameworks—including MCP-native ones—this is a few dozen lines at most.
4. Test with a harness
Use a lightweight test harness that runs the same scenarios against every adapter. If a skill passes on one agent but fails on another, the bug is almost always in the adapter or the contract—not the core logic.
5. Publish and version
Treat skills like packages. Version them, document them, and share them. GitHub's ecosystem now supports skill registries that make discovery straightforward.
Common Pitfalls
Looking Ahead
The convergence around MCP-compatible tool definitions means portability is finally more practical than rebuilding. Teams that invest in clean contracts and thin adapters today will save themselves rewriting the same skills for every new agent that arrives next quarter.
Get Involved
Explore github.blog for more guides, and follow Andrea at @AndreaGriffiths11 for ongoing developer tooling coverage.
via GitHub AI Blog