Notice: Claude wrote some of this.
Skills that let an AI agent work with your Johnny.Decimal system. Read and write your JDex, find your files, and keep your notes up to date.
There are two routes. Pick one. Both together gives you every skill twice.
This is the preferred route. It is for Claude Code, Codex, Cursor, and every other agent. You can edit the skills.
npx skills add johnnydecimal/skills
To update the skills later:
npx skills update
Refer to the skills tool for its other commands.
Or copy the folders in skills/ into your agent's skills directory yourself. For Claude Code that is ~/.claude/skills/ for every project, or .claude/skills/ for one.
A read-only bundle that Claude Code updates for you.
claude plugin marketplace add johnnydecimal/skills
claude plugin install johnnydecimal-skills@johnnydecimal
Or, from inside a session, /plugin marketplace add johnnydecimal/skills and then /plugin install johnnydecimal-skills@johnnydecimal.
Reads and writes your JDex, your Johnny.Decimal index. Ask it to find a file, look up an ID, trace how something works, or write a note. Invoke it by mentioning your JDex, for example "read my jdex and catch up".
To make a new ID or work package, it runs the JD CLI, jd new. It never writes a new ID by hand. If the CLI is not installed, it gets the install steps from the MCP server.
To put your existing files into your system, it calls the server's move_in tool and follows that process. The JD CLI moves each file, with jd move. The skill moves nothing itself. Neither the skill nor the CLI deletes a file.
When it files a file, it proposes a name for it. A batch with an obvious group, such as one account or one trip, gets a subfolder, and you say yes first. The rules come from the published pages on naming files and subfolder patterns, so the skill keeps no copy of them.
Reference material on how Johnny.Decimal works. You do not invoke this one. The jdex skill loads it when it needs it.
Create ~/.config/johnnydecimal/config.json:
{
"version": 1,
"systems": [
{ "root": "/path/to/your/filesystem", "jdex": "/path/to/your/jdex" }
]
}rootis your Johnny.Decimal filesystem.jdexis your index, for example your Obsidian vault.- With more than one system, mark the usual one
"default": true, and give each a"sys"— its system identifier, theSYSinSYS.AC.ID.
If you skip this, the skill has the JD CLI write it: jd agent-setup prints a prompt that finds your systems and writes the file.
The path follows the XDG Base Directory Specification. If you set $XDG_CONFIG_HOME, the file is $XDG_CONFIG_HOME/johnnydecimal/config.json. If you set $JD_CONFIG, the skill reads only that file. If you have the JD CLI, the skill gets the path from jd paths config.
Before version 4.0 of the JD CLI, the file was ~/.jd/config.json. If your file is still there, the skill continues to read it, and tells you that you can move it.
The skills get their Johnny.Decimal knowledge from the MCP server rather than carrying a copy, so they stay current.
claude mcp add --transport http jd https://johnnydecimal.com/mcp
Sign in when prompted. The documentation tools work with any account. The tools that serve a published system need an account that owns that system.
jd new makes IDs and work packages. jd move puts your files into your system, and 3.3.0 or later renames them and makes subfolders as it goes. Ask your agent to install the JD CLI. The MCP server has the steps. Without it, the skill reads and writes notes, but it makes no new IDs and moves no files.
jdex works on one ID at a time. It finds that ID in this order:
- An ID at the start of the current folder's name, for example
12.34 My folder. Open Claude in an ID folder and it knows the ID. - A
.jd/config.jsonin the current folder, or the nearest one above it:Add{ "id": "12.34" }"sys"when you run more than one system. - An ID at the start of a parent folder's name, nearest first. This is for
when you are in a subfolder, such as
12.34 Receipts/2026-03. - It asks you.
It will not guess, and it will not go looking through your JDex for a match.
AC.05 belongs to the agent. It keeps its notes there, so a later session can
read them back, and it is where you leave standing instructions for that part
of your system: how you name things, how you like a note laid out, anything you
want followed.
They are normal notes, so you can read and edit them yourself at any time. The skill reads the narrowest one that applies, then the wider ones:
13.05, for anything in category 13.10.05, for anything in area 10-19.00.05, for the whole system.
A narrower note wins over a wider one, and any of them beats the skill's own defaults.
You start with none of these. Tell the skill a rule and it writes the note for
you, named AC.05 AI for <location> ✨ to match the AC.01 inbox beside it,
for example 13.05 AI for category 13 ✨.
They answer different questions. Tell them apart by their keys.
| File | Question | Key |
|---|---|---|
~/.config/johnnydecimal/config.json |
Which systems do I have, and where? | systems |
./.jd/config.json |
Which ID is this folder about? | id |
Neither overrides the other.
Each skill is a folder under skills/ with a SKILL.md. Beside it, agents/openai.yaml gives Codex a display name and a short description. Add both to a new skill, and add the folder to the skills list in .claude-plugin/plugin.json.
The version number is in .claude-plugin/plugin.json. Bump it, and add a line to CHANGELOG.md, with every change that reaches a skill. Claude Code uses the version to decide when installed users get the update.
To release, fast-forward main to the work. On main, commit the changelog entry and the new version together, with the subject X.Y.Z: <headline>. Tag that commit vX.Y.Z, push main and the tag, and make a GitHub release with the changelog entry as its body:
git tag -a v1.4.0 -m "1.4.0: <headline>"
git push origin main v1.4.0
gh release create v1.4.0 --title 1.4.0 --notes-file <the entry>
Check your work with:
claude plugin validate . --strict
claude plugin validate skills --strict
MIT. See LICENSE.