Portable AI Agent Skills: One Skill, Every Model

Table of Contents

• The Problem: One Skill, Three Copies
• A Canonical Source of Truth
• Porting a Third-Party Plugin Without Losing Your Rules
• Fixing Cross-References Before They Break
• Sync, Don't Copy-Paste
• FAQ

The Problem: One Skill, Three Copies

We run three AI coding tools day to day: Claude Code, Codex, and Gemini CLI. Each has its own idea of what a "skill" is — a markdown file with instructions the model loads before acting. The trap is obvious in hindsight: write a skill for Claude, then hand-copy it into the Gemini config, then again for Codex. Three copies drift apart within a month. One gets a bug fix, the other two don't.

Model Context Protocol Entwicklung and MCP-based skill config solve half the problem — they standardize what an agent can call. They don't solve where the instructions live. That's a filesystem and process problem, not a protocol problem.

A Canonical Source of Truth

Our fix: a single directory, ~/.agents, holds every portable skill as a plain folder with a SKILL.md — YAML frontmatter (name, description) plus markdown body. No agent-specific syntax inside. A small PowerShell sync script then either symlinks that folder into Claude's and Codex's native skill directories, or — for Gemini, which reads ~/.agents/skills directly — does nothing at all.

The rule that keeps this from rotting: edit the canonical copy, never the linked one. A sync.ps1 dry-run reports every pending change and every conflict before anything touches disk; -Apply only runs after a human reads that report.

Porting a Third-Party Plugin Without Losing Your Rules

The harder case: adopting someone else's plugin. We installed a community blog-automation plugin built for Claude Code — 32 sub-skills, five subagents, real Python tooling for schema validation, fact-checking, and SEO scoring. Wanted it everywhere, not just Claude.

Three categories emerged fast:

1. Portable as-is — SKILL.md files using the same plain frontmatter format we already standardized on. Straight copy.
2. Portable with fixes — Python scripts and shared reference docs, callable by any agent via shell, but written with paths relative to the plugin's own folder layout.
3. Not portable — Claude-specific subagent definitions (a delegation format Gemini and Codex don't share). Left Claude-only rather than forcing a bad translation.

We vendored the plugin's repo into a stable path outside Claude's version-pinned plugin cache — that cache gets silently replaced on update, which would break anything pointing into it.

Fixing Cross-References Before They Break

Category 2 above nearly bit us. Several sub-skills referenced a shared references folder and sibling scripts using paths like skills/blog/references/visual-media.md — valid only when the whole plugin repo sits at a known relative root. Flatten those files into a shared skills directory and every reference silently breaks the moment an agent tries to open a file that isn't where the instructions say it is.

The fix was mechanical, not clever: rewrite every relative reference to an absolute path pointing at the vendored repo before copying anything into the shared skills folder. Verify with a grep pass, not a hope, that no relative path survived the move.

Sync, Don't Copy-Paste

The last mile is discipline, not tooling — the same discipline behind LLM Tool Integration Laravel work, where a tool definition drifting from its backend contract breaks silently instead of loudly. Every new portable skill goes into the canonical directory first. The sync script's dry-run output — changes, conflicts, verified-unchanged — is the actual gate, the same way draft: true gates a blog post before it ships. Skip the dry-run once, and you're back to three copies drifting apart.

The payoff isn't abstract: fewer prompts explaining the same convention three times, one place to fix a bug instead of three. Same discipline we bring to client work — Custom MCP Server Development, n8n Automatisierung Agentur Deutschland pipelines, Individualsoftware entwickeln lassen — config living in one engineer's head isn't infrastructure, it's a liability. We covered the orchestration layer these skills run inside in our MCP engineering piece and the harness/SDK architecture in our agent swarms breakdown. Need this built into your Software Development pipeline instead of duct-taped between tools? That's Geschäftsprozesse Automatisieren Agentur work.

FAQ

Do Claude Code, Gemini CLI, and Codex read skills the same way? No. Claude and Codex expect skills inside their own native directories (symlinks work fine); Gemini CLI can read a shared folder directly if pointed at it in its global instructions file.

What happens to features that only work in one tool, like Claude subagents? Leave them where they work. Forcing a translation into a format the target tool doesn't support produces something that looks portable but silently fails.

Is vendoring a plugin repo instead of using the tool's plugin manager overkill? Not if the plugin manager's cache is version-pinned and gets replaced on update — which several are. A stable, separately-updated copy is what makes absolute-path references reliable.

---

Photo by Sigmund via Unsplash.