# Manage Skills

> Find, add, update, and share agent skills in this repo. Use when asked to "find a skill" for a task, "build a skill" or "create a skill" (this skill checks whether one already exists - in the repo, the shared commons, or a public catalog - before authoring a new one), "update a skill", or reconcile a local skill change against the upstream commons vs a repo-local overlay. Covers the find-first bu…

- **Type:** Skill
- **Install:** `agentstack add skill-jeremykuhne-agent-skills-manage-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JeremyKuhne](https://agentstack.voostack.com/s/jeremykuhne)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JeremyKuhne](https://github.com/JeremyKuhne)
- **Source:** https://github.com/JeremyKuhne/agent-skills/tree/main/skills/manage-skills

## Install

```sh
agentstack add skill-jeremykuhne-agent-skills-manage-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Manage skills

If `overlay.md` exists beside this file, read it before acting; it contains
repository-specific bindings. This core remains usable without it.

The lifecycle skill for the skills under a repo's `.agents/skills/`: discover one,
add one, update one, and keep local changes in sync with the shared set. It turns
"find a skill", "build a skill", and "update the skill" into actions aligned with
the sharing model instead of ad-hoc edits.

The model in one paragraph: skills are authored once as a portable **core** and
shared through a common skills repo (the **commons**); each consuming repo holds a
pinned, provenance-stamped **copy** plus a thin repo-specific **overlay**. The
commons is bidirectional - a generic improvement made in any repo flows back
upstream, while a repo-specific tweak lives only in that repo's overlay.

## The three verbs

| Ask | Do | Detail |
| --- | --- | ------ |
| "find a skill for X", "is there a skill that does X" | Tiered search (local -> commons -> public), with an applicability check for this repo. | [find.md](find.md) |
| "build a skill for X", "create a skill" | **Run find first.** Only author new if it exists nowhere; otherwise vendor or tweak the existing one. | [build.md](build.md) |
| "update the skill", "sync my change", "pull skill updates" | Pull upstream drift; or push a local improvement, classified common (ask before upstreaming) vs deviation (overlay). | [update.md](update.md) |

These chain: `build` always begins by running `find`, and a `find` that turns up a
local skill needing a tweak hands off to the overlay path in `build`.

## The golden rule

When you change a skill that was vendored from the commons: **never let a vendored
core diverge silently.** A vendored core is a mirror of upstream. Classify the
edit, then place it - and **nothing about upstreaming is automatic**:

- **Local deviation** (the change is specific to this repo) -> move it into the
  repo's **overlay**, and restore the vendored core to match upstream.
- **Common** (the change helps every consumer) -> it *should* go upstream, but
  upstreaming is not always plausible. **Ask** before attempting it; never open a
  commons PR unprompted. If upstreamed, re-pin to the new version; if not yet,
  keep it as a recorded *pending-upstream divergence* so it is intentional, not
  silent.

So a vendored-core edit ends in one of three **recorded** states - upstreamed,
moved to the overlay, or a tracked pending-upstream divergence - never an
unexplained one. The provenance frontmatter (source repo, ref, and tree SHA) plus
the `update` drift check is what enforces this: unexplained drift is the signal
that an improvement was written into the wrong layer. See [update.md](update.md).

## Conventions every skill follows

Whatever the verb, the result must satisfy the repo's authoring rules
(`FORMAT.md`) and then pass `agent-files-review`, which owns the file-level
checks - frontmatter, mirror sync, whitespace, and the validator and link
checker. Don't restate those rules here.

For the `SKILL.md` frontmatter check specifically, this skill bundles
[scripts/Validate-Skills.ps1](scripts/Validate-Skills.ps1) - a dependency-free
PowerShell port of the Agent Skills spec validator - so the check runs anywhere
the skill is vendored, without the upstream tool. Run it on the skill directory:
`pwsh scripts/Validate-Skills.ps1 `. A commons portfolio uses
`-RequirePortfolioMetadata` to enforce its metadata and overlay contract.

For a new downstream binding, start from
`assets/overlay.md.tmpl`, replace its skill and pin tokens, and keep every local
path and concrete cross-reference in that overlay.

## Sub-pages

- [find.md](find.md) - the tiered search, the applicability check, and the
  recommendation report.
- [build.md](build.md) - the find-first decision tree, the security gate for
  public sources, and authoring a new skill (born-local vs born-shared).
- [update.md](update.md) - the pull (drift) and push (common vs deviation)
  flows and the provenance mechanics behind the golden rule.

## Disambiguation

`manage-skills` operates on the **catalog lifecycle** - discover, add, vendor,
sync. It is not `agent-files-review`, which
validates the **syntax and conventions** of one agent file (frontmatter, mirror
sync, whitespace). The normal order is: run `manage-skills` to bring a skill in
or push one out, then `agent-files-review` to validate the file you ended up with.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JeremyKuhne](https://github.com/JeremyKuhne)
- **Source:** [JeremyKuhne/agent-skills](https://github.com/JeremyKuhne/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jeremykuhne-agent-skills-manage-skills
- Seller: https://agentstack.voostack.com/s/jeremykuhne
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.