Skip to content

fix(list-skills): discover every installed skill, drop the PyYAML import #1187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
potiuk merged 2 commits into from
Sep 9, 2026
Merged

fix(list-skills): discover every installed skill, drop the PyYAML import #1187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
817ffec
fix(list-skills): discover every installed skill, drop PyYAML
potiuk Sep 9, 2026
f0ba953
fix(list-skills): keep Step 1's command literal so the evals can pin it
potiuk Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 79 additions & 29 deletions skills/list-skills/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,15 @@ name: magpie-list-skills
family: utilities
mode: Meta
description: |
Print a human-readable index of every skill in this repository,
grouped by family prefix (`pr-management`, `security`, `setup`,
…) with each skill's name and the first sentence of its
`description`. The listing is generated on every run from the
live `.claude/skills/*/SKILL.md` files, so it never goes stale
when skills are added, removed, or rewritten.
Print a human-readable index of every skill installed for this
repository, grouped by the family each one declares, with the
name to invoke it by and the first sentence of its
`description`. Discovery is installation-aware: it covers a
pinned snapshot install, the framework checkout, and
marketplace plugin installs, so the index matches what the
agent can actually run. Generated on every run from live
`SKILL.md` frontmatter, so it never goes stale when skills are
added, removed, or rewritten.
when_to_use: |
Invoke when a human asks *"what skills are available"*, *"list
the skills"*, *"show me the skills in this repo"*, *"give me a
Expand All @@ -35,20 +38,34 @@ license: Apache-2.0

# list-skills

Print a human-readable index of the skills in this repository.
The index is generated on every run from the live
`.claude/skills/*/SKILL.md` files — there is no cached copy to
keep in sync. The skill exists for humans (newcomers reading the
repo, maintainers checking what is available); agents route
invocations via the same frontmatter the script reads, so this
skill is purely informational.
Print a human-readable index of the skills installed for this
repository. The index is generated on every run from live
`SKILL.md` frontmatter — there is no cached copy to keep in sync.
The skill exists for humans (newcomers reading the repo,
maintainers checking what is available); agents route invocations
via the same frontmatter the script reads, so this skill is
purely informational.

What counts as "installed" depends on how Magpie was put in
place, so the script covers all three shapes and labels which one
each entry came from:

| Install | Where the skills live | Invocation shown |
|---|---|---|
| Pinned snapshot | `.agents/skills/` plus the per-agent relays beside it | `/magpie-<skill>` |
| Framework checkout | the repo's own `skills/` | `/magpie-<skill>` |
| Marketplace plugin | the plugin cache this script runs from, and its sibling plugins | `/<plugin>:<skill>` |

---

## Prerequisites

- Python 3.9+ on `PATH` with `PyYAML` importable. The framework's
Python toolchain already meets this; no extra setup.
- Python 3.11+ on `PATH`. Nothing else — the script is
stdlib-only, as `skills/pyproject.toml` requires of every
helper script in this tree, and declares that contract in
[PEP 723](https://peps.python.org/pep-0723/) inline metadata.
`uv run --script` and a bare `python3` therefore behave
identically.

---

Expand All @@ -61,26 +78,54 @@ verbatim:
python3 .claude/skills/magpie-list-skills/scripts/list_skills.py
```

Run that command **literally**, as written — do not expand it to
an absolute path. It is a repository-relative path that resolves
under both install methods that put skills in the repository: a
pinned snapshot install and the framework checkout both carry
`.claude/skills/magpie-list-skills` as a symlink onto the real
skill directory.

For a layout that puts each description on its own indented line
(easier to read when descriptions are long), pass `--verbose`:
(easier to read when descriptions are long), pass `--verbose`; to
inspect a repository other than the enclosing one, pass `--root`:

```bash
python3 .claude/skills/magpie-list-skills/scripts/list_skills.py --verbose
python3 .claude/skills/magpie-list-skills/scripts/list_skills.py --root /path/to/repo
```

The script:
**Marketplace installs are the one exception.** They write nothing
into the repository, so that path does not exist — the skill lives
in the plugin cache. Build the command from the base directory
reported for this skill instead:

- walks `.claude/skills/*/SKILL.md` relative to its own location;
- parses each skill's YAML frontmatter for `name` + `description`;
- groups skills by family prefix (the first hyphen-separated
token, with `pr-management` recognised as a two-token family —
see [`KNOWN_TWO_TOKEN_FAMILIES`](scripts/list_skills.py));
- prints each skill with the first sentence of its description.
```bash
python3 <the base directory reported for this skill>/scripts/list_skills.py
```

The script:

When a new multi-token family appears (e.g. a hypothetical
`docs-build-*`), add the prefix to `KNOWN_TWO_TOKEN_FAMILIES` in
[`scripts/list_skills.py`](scripts/list_skills.py); otherwise the
new skills land under the single-token head.
- resolves the repository from `git rev-parse --show-toplevel`
(or `--root`), **not** from its own location — under a
per-family plugin install its own location is one family, not
the whole install;
- walks the agent-target directories that install writes into
(`.agents/skills/` and its relays — the registry in
[`../setup/agents.md`](../setup/agents.md) is the source of
truth), the framework's own `skills/` when the repo is the
framework checkout, and the sibling plugins in the marketplace
cache when it is running from one;
- de-duplicates by the name you would type, so relay directories
collapse to one entry while a skill available from *two*
install methods keeps both — they are two different things to
type;
- groups by each skill's declared `family:` frontmatter key, per
Golden rule 8. Family is **never** inferred from the name
prefix: `repo-health` and `contributor-growth` span several
prefixes, and `write-skill` is family `utilities`, not family
`write`. A skill that declares no family lands in `other`;
- prints each entry with the first sentence of its description,
then a summary of which install each entry came from.

---

Expand All @@ -97,7 +142,8 @@ read that skill's `SKILL.md` and answer from it.
## Hard rules

- **Read-only.** This skill never edits, creates, or deletes
files. It only reads `SKILL.md` files under `.claude/skills/`.
files. It only reads `SKILL.md` files under the install
directories listed above.
- **No paraphrasing.** Always present the script output verbatim.
Paraphrasing reintroduces the staleness this skill exists to
prevent.
Expand All @@ -110,7 +156,11 @@ read that skill's `SKILL.md` and answer from it.
listing script Step 1 invokes.
- [`AGENTS.md`](../../AGENTS.md#reusable-skills) — the
framework's "Reusable skills" section, which explains the
`.claude/skills/` layout and frontmatter convention.
skills layout and frontmatter convention.
- [`../setup/agents.md`](../setup/agents.md) — the agent-target
registry the discovery list mirrors.
- [`../../docs/setup/marketplaces.md`](../../docs/setup/marketplaces.md)
— why the invocation name differs between install methods.
- [`write-skill`](../write-skill/SKILL.md) — sibling skill for
authoring a new skill. Use it when the listing reveals a gap
that warrants a new entry.
Loading