Agent Skill Manager: Organize and Control SKILL.md

An agent skill manager is the control plane for discovering, organizing, updating, scoping, and safely retiring Agent Skills across AI coding agents. When SKILL.md packages spread across Claude Code, Codex, OpenCode, OpenClaw, and Pi, a folder of installed skills is no longer enough. You need to know which skills are active, where every copy came from, which revision each project uses, whether an update is safe, and what can be removed without breaking a workflow.

That is the problem SelfTune's new Skill Manager is designed to solve.

What is an Agent Skill Manager?

Agent Skills are portable folders that give an AI agent specialized instructions, workflows, scripts, references, and assets. Each skill has one required entry point: SKILL.md.

People frequently search for skills.md, but the open Agent Skills standard uses the singular, uppercase filename SKILL.md inside each skill directory. A typical package looks like this:

research-skill/
├── SKILL.md
├── workflows/
├── scripts/
├── references/
└── assets/

Agent Skills use progressive disclosure. The agent first sees each skill's name and description. When a request matches, it loads the full SKILL.md and then opens supporting resources only when needed. This is much more efficient than putting every instruction in an always-on AGENTS.md or CLAUDE.md file.

Progressive disclosure solves package-level context loading. It does not solve skill management.

An Agent Skill Manager must answer questions that the filesystem cannot:

Question	What the manager needs to know
What skills do I have?	Every global, project, cached, draft, and archived package
Where is a skill active?	Its paths, scope, harnesses, links, and project placements
Are two copies the same?	Their content revisions, not just their directory names
Is an update available?	The recorded source, upstream state, and local modifications
Is a skill useful?	Trusted usage evidence, routing health, and recent activity
Can I remove it safely?	Dependencies, evidence quality, protection rules, and an undo path
Which skills belong in this project?	A pinned, reproducible Skill Set with a preview and receipt

A marketplace helps you find more skills. A skill installer copies them into an agent. A file browser helps you open SKILL.md. A real skill manager operates the full lifecycle after installation.

Why Agent Skills become hard to manage

Installing an AI agent skill is easy. Operating dozens or hundreds of them is where the system starts to break down.

1. Every active skill competes for discovery context

The full skill body loads on demand, but the agent still needs enough metadata to discover the right skill. Large catalogs create more overlapping descriptions, more ambiguous routing, and more context pressure. Some harnesses eventually cap, exclude, or deactivate skill descriptions when the active catalog grows too large.

The result is counterintuitive: adding more Agent Skills can make the right skill less likely to activate.

A skill manager therefore needs to control the active catalog, not merely list everything that has ever been installed.

2. One skill can exist in many places

The same logical skill might appear in a global Claude Code directory, a Codex registry, several projects, a package cache, and an archive. Some placements are copies. Others are symlinks. Two directories may share a name while containing different versions.

Without reconciliation, there is no reliable answer to a basic question: "Which SKILL.md did my agent actually use?"

3. Upstream updates conflict with local improvements

Agent Skills become more valuable when you adapt them to your terminology, tools, and quality bar. But local edits complicate updates from the original author.

Blind replacement preserves freshness by deleting local learning. Never updating preserves local customization by accepting permanent drift. A skill manager must make the source, installed revision, local changes, and candidate update visible before anything is overwritten.

4. "Unused" is not the same as "safe to delete"

A rarely invoked incident-response skill may be valuable precisely because the incident is rare. A skill with no usage records may be inactive, or the manager may simply lack telemetry from the agent where it runs.

Deleting skills based on a last-access timestamp is not lifecycle management. It is guesswork.

5. Global installation is the wrong default for project work

A research repository, marketing site, and deployment project do not need the same active Agent Skills. Installing every skill globally increases routing noise and makes project behavior harder to reproduce across teammates and machines.

Skill management needs a project-level distribution primitive: a small set of known revisions, applied only where they belong.

SelfTune: a local-first Agent Skill Manager

SelfTune started by measuring whether skills activate and execute correctly. The Skill Manager extends that evidence model across the rest of the lifecycle: inventory, updates, project distribution, cleanup, backup, and improvement.

One Skill Library across every supported agent

SelfTune's Skill Library scans the locations where Agent Skills actually live across Claude Code, Codex, OpenCode, OpenClaw, and Pi. It reconciles duplicate installations, project and global placements, immutable cached revisions, drafts, and reversible archives into one inventory.

For each skill, the manager shows:

• every concrete path and whether it is global or project-scoped;
• the agents and harnesses where it is available;
• the package revision and modification time;
• the installed source and upstream update state; and
• the last trusted invocation SelfTune observed.

Ten paths do not necessarily mean ten skills. Two packages named research do not necessarily contain the same SKILL.md. The Library keeps the logical package, physical placements, and immutable revisions distinct.

It also refuses to invent provenance. GitHub-backed Agent Skills can be checked against recorded install metadata and the upstream repository tree. Local or unsupported sources are labeled as untracked or unavailable instead of being guessed.

You can inspect the Library in the SelfTune desktop app or from the CLI:

selftune library

Evidence-aware cleanup with reversible quarantine

SelfTune's skill portfolio audit separates missing evidence from measured inactivity. Instead of one misleading "unused" label, it classifies skills as:

• Unobserved: installed, but there is not enough trustworthy evidence.
• Under-observed: some evidence exists, but the sample is too small.
• Routing problem: relevant reads are not becoming reliable invocations.
• Active: recent use with sufficient evidence.
• Inactive candidate: enough subsequent sessions exist to justify review.
• Consolidation candidate: sibling skills or usage patterns suggest overlap.

selftune skills audit --json

The audit recommends an action. It never deletes a package automatically.

When you approve cleanup, quarantine moves the complete skill outside active agent registries, records its hash and original location, and returns an exact restore command. SelfTune and system-managed packages are protected. Restore refuses to overwrite a new package that has taken the old path.

This makes the active skill catalog smaller without making cleanup irreversible.

Project-specific Skill Sets instead of global sprawl

SelfTune Skill Sets define a reusable collection of Agent Skills for a project. Every package is pinned to an immutable content revision, so the same set means the same thing on another machine.

selftune sets plan --set research-project --project /path/to/project
selftune sets apply --set research-project --project /path/to/project

The plan shows every path that would be created, left unchanged, or conflict. One conflict blocks the entire operation before any mutation. A successful apply prefers links to SelfTune's verified content-addressed Library, and a receipt records exactly which paths SelfTune owns.

Rollback removes only receipt-owned paths. It blocks if a linked or copied package changed after apply. The pinned Library revision remains available.

This keeps the useful property of symlinks—one verified package instead of uncontrolled copies—while adding what symlinks alone cannot provide: a manifest, revision pinning, conflict handling, ownership, and rollback.

Skill Sets can target Claude Code, Codex, OpenCode, OpenClaw, and Pi. They can also be derived from an existing project and exported as portable manifests without absolute device paths or credentials.

Guarded source updates that preserve local work

For GitHub-backed skills, SelfTune records source metadata and the installed revision, checks the upstream repository tree, and previews available changes. If the installed package contains local modifications, replacement is blocked by default.

An explicit replace action keeps a complete backup and update receipt.

This is deliberately conservative. SelfTune does not claim to perform a trustworthy semantic merge between every upstream change and every local adaptation. It provides the provenance, preview, conflict signal, backup, and reversibility needed to make that decision without silently losing work.

Skill improvement based on real usage

Most skill managers stop after install and update. SelfTune also measures how Agent Skills behave.

It separates two different failure modes:

1. Activation: did the agent select the skill for the right request?
2. Execution: after loading SKILL.md, did the workflow produce the right result?

SelfTune can use real agent sessions to propose improvements, then test a candidate against positive, negative, boundary, and execution cases. Its local synthesis inbox can also identify repeated successful work that is not yet covered by a skill, or stable combinations that may belong behind one coherent workflow instead of several top-level descriptions.

Candidates require human review. A detected pattern does not automatically install, archive, or publish anything. Evaluation compares the candidate with no-skill and existing-skill baselines, uses held-out evidence, and checks for regressions before release can be recommended.

The goal is not to replace 20 arbitrary Agent Skills with one arbitrary meta-skill. It is to earn a smaller and more useful skill surface through evidence.

Local by default, remote when you choose

Skill discovery, supported agent histories, normalized evidence, portfolio audits, synthesis, and the SelfTune dashboard can remain on your machine.

Remote Library solves a separate, optional problem: backup, multi-device access, and private sharing for immutable skill revisions, Skill Sets, decisions, and selected redacted summaries. Raw transcripts are not part of Remote Library sync.

Before sync, SelfTune previews the exact artifacts, file names, sizes, hashes, and bounded content that would cross the remote boundary.

An Agent Skill Manager should make your environment more legible without quietly making it less private.

Skill Manager vs. marketplace vs. installer

These tools solve different parts of the Agent Skills lifecycle:

Tool	Primary job
Skill marketplace	Discover public Agent Skills
Skill installer	Copy or link a skill into an agent registry
SKILL.md editor	Create and edit an individual skill package
Agent Skill Manager	Reconcile inventory, scope projects, track revisions, guard updates, audit usage, quarantine safely, and roll back changes

The ecosystem needs all four. The mistake is expecting an install command to keep hundreds of evolving packages healthy after they land on your machine.

A practical Agent Skill Manager workflow

The smallest useful SelfTune workflow is:

1. Inventory: run selftune library to reconcile installed skills and inspect their sources, revisions, locations, and update state.
2. Audit: run selftune skills audit --json to separate active, under-observed, routing-problem, inactive, and consolidation candidates.
3. Reduce: quarantine approved inactive packages and keep the returned restore command.
4. Scope: create a pinned Skill Set for each project archetype instead of activating the complete global catalog everywhere.
5. Preview: run selftune sets plan before applying a set or changing any project path.
6. Improve: measure activation and execution before changing SKILL.md, then verify the candidate against realistic positive and negative cases.

That turns a directory of prompts into an operated system.

Agent Skill Manager FAQ

Is `SKILL.md` the same as `skills.md`?

No. The open Agent Skills standard uses a file named SKILL.md—singular and uppercase—inside each skill package. The search term "skills.md" is common, but it is not the standard package entry-point filename.

Do Agent Skills use context even when they are not activated?

The full SKILL.md body loads only after activation, but an agent generally needs access to each available skill's name and description for discovery. Large or overlapping catalogs can therefore create metadata pressure and routing ambiguity even with progressive disclosure.

Can one Skill Manager handle Claude Code skills and Codex skills?

Yes. SelfTune reconciles Agent Skills across Claude Code, Codex, OpenCode, OpenClaw, and Pi. It records each physical placement separately while grouping identical content revisions into one logical Library inventory.

How many Agent Skills should a project have?

There is no universal number. The useful limit depends on description overlap, harness behavior, and the work the project performs. The better rule is to keep only relevant skills active in each project, measure whether they are used, and move supporting procedures behind progressive disclosure where possible.

Does SelfTune automatically delete unused skills?

No. SelfTune distinguishes missing evidence from inactivity. Quarantine requires explicit approval, preserves the complete package and its original path, and provides a receipt-based restore command.

Manage the Agent Skills you already have

The first generation of Agent Skills tooling answered, "How do I install this?"

The next question is, "How do I operate all of this without losing reliability?"

SelfTune's Skill Manager provides one reconciled inventory, evidence-aware cleanup, project-specific Skill Sets, guarded source updates, receipts, rollback, and measured improvement for the SKILL.md ecosystem.

SelfTune is open source. Download the desktop app, read the Agent Skills guide, or install the SelfTune agent skill to inspect the skill system you already have.