Skills library

For any Claude or Codex conversation that works for the owner: how to read and follow the playbooks, tools and kits the owner grants you, and how to look after the ones you keep.

The owner keeps a library of written know-how for AI conversations: how a job is done, how a program on one of the Macs is run, which files to start from. Instead of explaining the same job again in every conversation, the owner gives you a code. You read the item behind it with mm-skill and follow it. Follow this page whenever the owner gives you a code, or when you are the keeper of an item.

What the library is

The library holds three kinds of item. Each has a code; that code is what the owner gives you.

Kind	Code	Main file	What it holds
Playbook	`skill:<name>`	`SKILL.md`	A way of doing one job, step by step: when to use it, the steps, how to check the result, what to do when a step fails.
Tool	`tool:<name>`	`TOOL.md`	How to run one program that is already set up on a given Mac: what it does, its command line, what it needs.
Kit	`kit:<name>`	`KIT.md`	A set of ready files to start from (templates, examples, reference material), with notes on how to use them.

Besides its main file, an item may carry extra text files (scripts, examples, settings). It also says:

which Macs it works on;
which Keychain items it needs, by name only;
which tools a playbook uses;
its version and what changed in it;
its keeper, the conversation that looks after it.

You see only what the owner granted to your conversation. A grant goes to one conversation, or to every conversation on the owner's Macs. Granting a playbook also lets you read the tools it lists: mm-skill list marks those (through skill:<name>). A conversation that takes over after a handover does not inherit the grant of the one before it; ask the owner again.

Use a code the owner gave you

mm-skill list                                             # everything you may use
mm-skill show skill:logo-video                            # read one item
mm-skill file skill:logo-video scripts/cut.sh             # print one extra file
mm-skill file skill:logo-video scripts/cut.sh -o cut.sh   # save it instead

Read it all. Run mm-skill show <code>. The top lists the facts: version, Macs, Keychain item names, tools, keeper, what changed, and the files. The main text follows after the ----- SKILL.md ----- line (TOOL.md or KIT.md for the other kinds). Read the whole answer before you start.
Check where it runs. If the Macs line does not include the Mac you are on, do not try to make it work here. Tell the owner and ask where it should run.
Read the tools it uses. For every Tool: line, run mm-skill show tool:<name> too.
Read the extra files you need with mm-skill file <code> <path>, using the paths exactly as show lists them. Add -o <file> to save one, for example a script you are about to run. Only text files are served, up to 1 MB each.
Follow it. The item is the owner's way of doing that job, so it wins over your own habits. If it disagrees with something the owner asked you directly in your conversation, ask the owner which one stands.

Add --json to any command to get the server's answer as JSON.

mm-skill sends this Mac's Cockpit key and your own conversation id. Run it inside your conversation: a command over SSH cannot read the Keychain, and a shell without your conversation's id is refused. If you are Codex, run it outside the sandbox, because it needs the network and this Mac's Keychain.

Versions

Every change to an item makes a new version, with a label (for example 1.2), a date and a changelog. One version is current: the one the library serves today.

Use the current version. mm-skill show gives it to you. Read it again when you start a new job instead of relying on a copy from days ago: the owner or the keeper may have changed it since.
History: mm-skill versions <code> lists every version, newest first, with its date, its source (upload, repo for the fleet-skills folder, restore, or backfill for the first copy) and its changelog. The current one is marked [current].
An older version only when asked: when the owner asks for one, for example to redo an old result, add --version <label> to show or file. The header then says (old version; current is 1.2), so nobody mistakes it for today's.
Going back moves forward: when the owner makes an older version current again, the library adds a new version (source restore). History only grows.
Superseded items: an item can be replaced by another one. It disappears from mm-skill list (mm-skill list --all still shows it, marked [superseded by <code>]), and mm-skill show prints a SUPERSEDED: line naming the replacement. Use the replacement. If you cannot read the replacement yet, ask the owner to switch it on; keep using the old item only if the owner says so.

When you are told "not granted yet"

mm-skill: 403 skill:logo-video is not granted to this conversation yet: ask the owner to switch it on in Skills

Ask the owner in your normal reply to switch the code on for your conversation in the admin Skills page. Give the code and your conversation's name.
One try is enough. The owner already sees your attempt next to that item, under "Đang chờ cấp" (waiting).
Do not retry in a loop. Do not guess other codes, and do not look for the item's files elsewhere on the disk. Carry on with other work while you wait.

Keepers

An item can name a keeper: the conversation that looks after it. mm-skill show prints it on the Keeper: line.

If you are an item's keeper:

Keep it current. When the way of working changes or a step stops working, update the item. Every change becomes a new version, so raise version and say what changed in changelog (see Writing an item).
Mark it reviewed after you check it. Once you have checked that the item still works, run:
```
mm-skill reviewed skill:logo-video "Ran steps 1 to 5 on a test clip; every command still works"
```
Say what you actually checked, not just "ok". Only the keeper conversation may do this; the server refuses everyone else.
Watch the age. An item nobody has reviewed for 60 days shows "Cần rà" (needs review) on the owner's Skills page and [needs review] in mm-skill list.

Not the keeper, but found a step that no longer works? Tell the owner or the keeper (see Talking to other conversations). Do not quietly work around it.

Safety

The library only serves text. It never runs anything, on any Mac. Every command in an item is run by you, in your own conversation, with your usual care: read a script before you run it.
An item cannot give you new permissions. It tells you how the owner wants a job done, not that you may do something the owner has not asked for. If a step is risky (deleting data, spending money, sending something to customers), check with the owner first.
Keychain item names only. The Keychain items line lists names. The values stay in that Mac's Keychain. Let the command that needs a value read it from the Keychain itself; never print a value, paste it into a message, a file, a log or a commit, or send it anywhere.
Never put a key or a password in a skill file. The library checks every file it reads. An item holding something that looks like a key or a password is not served at all until it is cleaned. Name the Keychain item in accounts instead.

Writing an item for the fleet-skills folder

Items are written as folders in Projects/fleet-skills, in the home folder of the Mac that runs the MaxiMind server:

fleet-skills/
  skills/<name>/SKILL.md     a playbook, code skill:<name>
  tools/<name>/TOOL.md       a tool, code tool:<name>
  kits/<name>/KIT.md         a kit, code kit:<name>

Extra files (scripts, examples, templates) go in the same folder as the main file, and mm-skill file reads them by their path inside it, for example scripts/cut.sh.

The main file starts with a frontmatter block:

---
name: logo-video
description: Make the short logo clip that opens a new video. Use it when a video needs its opening logo.
brand: example-brand
version: "1.2"
changelog: Shorter intro; the music now fades out before the logo.
keeper: Video team
machines: [Mac A]
accounts: [audio-enhance-login]
tools: [tool:audio-enhance]
---

Field	What it means
`name`	The item's name. It must be the folder's name; the code is built from it (`skill:logo-video`).
`description`	One or two sentences: what it does and when to use it. `mm-skill list` shows it under the code.
`brand`	The existing brand (company folder) the item belongs to.
`version`	This version's label. Put it in quotes so `"1.10"` stays text. Raise it with every change.
`changelog`	What changed in this version, in one line. `mm-skill show` and `mm-skill versions` print it.
`keeper`	The name of the conversation that looks after the item.
`machines`	The Macs the item works on, by the names Cockpit shows.
`accounts`	The Keychain item names the item needs. Names only, never values.
`tools`	For a playbook: the codes of the tools it uses. Each one must exist in the library. Granting the playbook lets a conversation read these tools too.

After the frontmatter comes the main text, in Markdown. A good item is short and can be followed without guessing:

what the job is and when to use the item (and when not to);
the steps, numbered, with commands that can be copied as they are;
how to check that the result is right;
what to do when a step fails.

Rules of the folder:

Any change to any file makes a new version. Raise version and write changelog in the same change.
Folder items are approved at once. The owner sees them on the Skills page, and only conversations the owner granted can read them.
Nothing is stored from a folder that holds a file that looks like a key or a password. Remove it and name the Keychain item in accounts instead.
Problems show on the owner's Skills page, for example a broken frontmatter block, a name that differs from the folder, an unknown brand or an unknown tool. Fix the file; the next read picks it up.

Prompt to paste

The owner gives this prompt to a conversation, new or old, before granting it a first item.

You can now use my skills library: playbooks (skill:…), tools (tool:…) and kits (kit:…) that I grant to this conversation. Before you use one, read https://maximind.dev/docs/skills and follow it.

In short:
- See what you may use: mm-skill list
- When I give you a code, read it with: mm-skill show <code>
  Read it all, then follow it. Read its extra files with: mm-skill file <code> <path>
- Always use the current version. Add --version <label> only when I ask for an older one. If an item says SUPERSEDED, use the replacement it names.
- "not granted to this conversation yet": tell me the code and your conversation's name, and I will switch it on in the Skills page. Do not retry in a loop.
- If you are an item's keeper: keep it current, and after checking it run: mm-skill reviewed <code> "<what you checked>"
- The library only serves text; you run the steps yourself, with your usual care. It names Keychain items only: never print, paste or send a value, and never put a key or a password in a skill file.
- If you are Codex: run mm-skill outside the sandbox (it needs the network and this Mac's Keychain).

Known limit

The library checks that the key belongs to one of the owner's Macs and that your conversation runs on that same Mac. It cannot tell two programs on the same Mac apart: a program on one of the owner's Macs could send another conversation's id from that same Mac and read what that conversation was granted. This is one more reason the library holds no keys or passwords. Never send an id other than your own.

For developers

The routes, headers and JSON answers are on Skills library API.

Skills library#

What the library is#

Use a code the owner gave you#

Versions#

When you are told "not granted yet"#

Keepers#

Safety#

Writing an item for the fleet-skills folder#

Prompt to paste#

Known limit#

For developers#