A Personal Skill Library You Can Carry Between Apps

By the second year of working with agents you have built up a private pile: a skill that walks through your release checklist, a prompt that writes changelog entries the way you like them, an MCP server config you have pasted into four projects, a rule about migrations you have typed out more times than you can count. It lives in one app, on one machine, and when you try a different agent or set up a new laptop, most of it does not come with you.

This guide is about turning that pile into something you own — one private repository that survives an app change, a machine change and a pricing change. It covers what is genuinely portable, what is welded to a single product, and the small amount of plumbing that connects the two.

What actually moves between apps

Three things are portable today, and two are not.

The Agent Skills format is the important one. A skill is a folder with a SKILL.md file: YAML frontmatter with name and description, then Markdown instructions, optionally with scripts/, references/ and assets/ alongside. The spec keeps the required surface deliberately tiny — name is up to 64 lowercase characters, hyphens allowed, and must match the folder name; description is up to 1024 characters and should say both what the skill does and when to use it. Optional fields are license, compatibility, metadata (an arbitrary string map) and the experimental allowed-tools.

That small surface is why the format travels. Anything beyond it may not. The specification itself, and a reference validator you can run against a folder, live in the Agent Skills standard repository.

The one path three apps agree on

Skills are portable; the folder they live in is not, quite. Each app scans its own locations:

• Claude Code: ~/.claude/skills/<name>/SKILL.md for personal skills, .claude/skills/ in the project, and nested .claude/skills/ in subdirectories.
• Codex: .agents/skills in every directory from your working directory up to the repository root, plus $HOME/.agents/skills.
• Cursor: .agents/skills/ and .cursor/skills/ in the project, ~/.agents/skills/ and ~/.cursor/skills/ globally — and, for compatibility, .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/ as well.
• VS Code and Copilot: .github/skills/, .claude/skills/ and .agents/skills/ in the workspace; ~/.copilot/skills/, ~/.claude/skills/ and ~/.agents/skills/ at user level.

Read that list again and .agents/skills stands out: Codex, Cursor and VS Code all scan it, at both project and user level. It is the closest thing the ecosystem has to a neutral home. Claude Code is the outlier, and one symlink closes the gap.

So the target layout is: skills live in your repository, ~/.agents/skills points at them, and ~/.claude/skills points at them too.

A layout that survives

One private git repository, not a folder in Dropbox. You want history, diffs and the ability to revert a skill that started misbehaving.

agent-kit/
├── skills/                  # SKILL.md folders, the portable core
│   ├── release-checklist/
│   │   ├── SKILL.md
│   │   └── references/rollback.md
│   └── changelog-entry/
│       └── SKILL.md
├── instructions/
│   ├── AGENTS.md            # the shared base you copy into projects
│   └── fragments/           # per-language and per-framework pieces
├── mcp/
│   └── servers.md           # which servers, which transport, which env vars
├── apps/
│   ├── claude-code/         # subagents, hooks, settings — not portable
│   └── cursor/              # .mdc rules — not portable
└── README.md                # how to install this on a fresh machine

Two rules keep it healthy. First, skills/ contains nothing app-specific: no Claude Code shell injections, no @file references, no context: fork. Those do not exist outside Claude Code, and a skill that relies on them is not portable however open the format is. Second, secrets never enter the repository — mcp/servers.md records that a server needs a token and what the variable is called, not the token.

Getting it onto a machine

For personal skills, symlinking beats copying: edit once, every app sees the change, and there is no sync step to forget.

ln -s ~/code/agent-kit/skills ~/.agents/skills
ln -s ~/code/agent-kit/skills ~/.claude/skills

That is the whole install on a new laptop, after the clone. Two caveats before you commit to it. Symlinks are not honoured identically everywhere — Claude Code documents restrictions on symlinked user-scope files in some session types, so start a session and confirm the skill appears rather than assuming. And on Windows, creating a symlink needs Developer Mode or administrator rights; directory junctions are the usual substitute.

For project-specific skills, copy instead, and commit the copy. A skill that encodes how this repository deploys belongs in the repository, in .agents/skills/ so several agents can find it, where it is reviewed and versioned with the code it describes.

If you would rather not manage the links yourself, that is a solved problem.

Skills Manager 🧩 SkillFree

Desktop app and CLI that keeps one skills library and symlinks it into 30+ AI coding tools

★ 1.0k · +12 this week

7.0 Visit ↗

Skills Manager keeps one central library and links it into each detected tool's folder — symlinks on macOS and Linux, directory junctions or tracked copies on Windows, so it works without administrator rights. You can enable a skill for one tool and not another without deleting anything, and its skm CLI (init, adopt, list, enable, disable, doctor) covers headless machines. Two things to know before installing: the macOS build is ad-hoc signed rather than notarised by Apple, and skm adopt moves your existing skills into the central hub, so take a backup of ~/.claude/skills before you run it.

Versioning, without a package manager

The Agent Skills spec has no version field. Its metadata map takes arbitrary string keys, and the spec's own example uses version: "1.0", which is a reasonable convention, but nothing enforces or reads it. Your version control is git, and that is fine:

• Tag when a skill changes behaviour, not on every typo fix. You want to be able to say "the release skill from before I moved to the new pipeline".
• One commit per skill change. When an agent starts doing something odd, git log -- skills/that-one/ is the fastest diagnosis you will get.
• Keep a one-line smoke test in each SKILL.md's own notes: the prompt that should trigger it, and the first action you expect. Thirty seconds of checking after an app upgrade beats discovering the breakage mid-task.

For skills you install from other people rather than write, a tool that records provenance is worth the extra step.

skilld 🧩 SkillOpen source

Registry and CLI to search, read, install and update human-authored Agent Skills

★ 308 · +1 this week

7.0 Visit ↗

skilld is a registry and CLI for skills published by named maintainers. The useful part for a private library is the workflow: skilld run <selector> prints a skill's SKILL.md to your terminal for one session without writing files or running anything, so you can read an author's instructions before your agent follows them. skilld install writes to each detected agent's folder and records the exact source commit in a lockfile, and skilld outdated tells you when the upstream repository has moved. It is MIT licensed and sends no analytics; note that it upgrades itself in the background unless you set SKILLD_NO_UPGRADE=1, and that "verified" in its registry means the provenance checks out, not that the instructions are good.

When the app changes under you

Skills break quietly, and always in one of three ways.

A field gets renamed. Cursor's skill loader still accepts the old globs frontmatter key as a fallback but tells you to use paths in new skills. Field drift like this is the most common breakage, and it produces a skill that loads but never triggers.

A location stops being scanned. Apps add and consolidate skill directories; VS Code has already deprecated one settings-based location. If a skill vanishes, check where the app is looking now before rewriting the skill.

The skill was never portable. If it works in Claude Code and nowhere else, check what it uses. Shell command injection, @ file references and subagent fields are Claude Code features. Skills synced to a claude.ai account are restricted to name, description, license, compatibility, metadata and allowed-tools — a useful test: if your frontmatter would not survive that filter, it is not a portable skill, it is a Claude Code skill.

The defence is boring and effective. Keep the portable core minimal, put the clever tool-specific parts in apps/, and after any agent upgrade run one skill and watch what happens.

What to actually put in it

Do not start from a blank folder. Install a few well-made skills, read their SKILL.md files, and copy the structure rather than the content.

Anthropic Agent Skills 🧩 SkillFree

Anthropic's official collection of Agent Skills, including document, design and developer skills

★ 179k · +1.2k this week

9.2 GitHub ↗

Anthropic's own repository is the reference implementation: around twenty skills, each a folder with frontmatter and instructions, plus supporting scripts and reference files that load only when needed. Read skill-creator to see how a skill is meant to be structured, and the document skills to see how a large one splits reference material out of SKILL.md. Check the licences before you copy: most are Apache 2.0, but the four document skills are source-available rather than open source, with terms tied to Anthropic's products. Some skills run Python or Node scripts on your machine, so test before relying on them.

Superpowers 🧩 SkillFree

A skills library that makes coding agents plan, test-first and debug systematically

★ 294k · +2.7k this week

9.0 GitHub ↗

Superpowers is the other end of the scale — a method rather than a utility. It gives the agent a full development loop: brainstorm, write a plan, execute it with test-driven development and code review between tasks. It is MIT licensed, documents installation for well over a dozen agents including Claude Code, Codex, Cursor, Gemini CLI and OpenCode, and its skills are plain SKILL.md folders, so it doubles as a large worked example of the format. Whether you adopt the method or not, its writing-skills skill is the clearest short statement of what a good skill looks like.

For everything else, browse by what the skill does rather than by app: the ecosystem map shows which apps each listing claims to work with, skills that work with Claude Code is a reasonable starting shelf, and the glossary untangles the vocabulary. If you are unsure whether the thing you need is a skill, a subagent, an MCP server or a line in an instructions file, our post on what each one does settles it in a page.

Publish it, or keep it

Publishing a skill is not the same as publishing a library. A skill is instructions that other people's agents will follow, on their machines, with their permissions. Treat it accordingly.

Publish when the skill is useful without your repository, contains no client names, internal URLs or credentials, states a license in its frontmatter, and you intend to keep it working. A single well-maintained skill is worth more than a repository of thirty you abandoned.

Keep it private when it encodes a client's process, when it only makes sense against your own codebase, when it documents a workaround for a security control, or when you simply do not want to answer issues about it. A private git repository with two symlinks is a complete, perfectly respectable distribution strategy for a library of one.

Do this next

1. Create one private repository with skills/, instructions/, mcp/ and apps/.
2. Move your existing skills into skills/ and link ~/.agents/skills and ~/.claude/skills at it.
3. Strip anything app-specific out of those skills and park it under apps/.
4. Install one good public skill, read its SKILL.md, and fix the weakest of yours to match.
5. Write the fresh-machine instructions in the README while you still remember them.

Before this pays off, the instructions the agent reads in every session need to be right: that is instruction files compared. If you are earlier in the journey, the beginner guides cover installing and running your first agent. And when a private library turns into something you want other people to install — versioned, documented, supported — the developer guides cover writing and distributing skills for other people.

Read the official docs for…

• The Agent Skills format: frontmatter fields, constraints and folder layout — agentskills.io/specification
• Claude Code skill locations, progressive disclosure and what does not work elsewhere — code.claude.com/docs/en/skills
• Cursor's skill directories and compatibility paths — cursor.com/docs/context/skills
• Codex skill scopes and scanning order — learn.chatgpt.com/docs/build-skills
• VS Code and Copilot skill folders and settings — code.visualstudio.com
• MCP config scopes and file formats per app — code.claude.com/docs/en/mcp