| name | johnny-decimal |
| description | > |
Johnny Decimal File Organization
Skill base directory: ${CLAUDE_SKILL_DIR}
This skill helps you work with the Johnny Decimal (JD) file system located at
~/Documents (or $XDG_DOCUMENTS_DIR).
Quick Reference
The system has 10 areas:
| Area | Purpose |
|---|
| 00-09 System | Meta-management (inbox, templates, scripts, archive) |
| 10-19 Personal | People (Self, Spouse, Kids, Parents, Friends, Pets) |
| 20-29 Finances | Banks, investments, credit, taxes, insurance |
| 30-39 Home and Property | Homes, vehicles, major assets |
| 40-49 Career and Education | Education, research, employers |
| 50-59 Health and Wellness | General health resources (not personal records) |
| 60-69 Hobbies and Recreation | Games, computing, creative works, travel |
| 70-79 Legal and Records | Legal documents and archival records |
| 80-89 Household and Services | Services, products, utilities, meals |
| 90-99 Reference | Library, research, manuals, datasets |
Structure Format
XX-XX Area Name/ # Area (decade range)
└── XX Category Name/ # Category (two digits)
└── XX.YY Subcategory/ # Subcategory (ID)
Example path:
~/Documents/20-29 Finances/21 Banks/21.10 Example Bank/
Key Principles
- One place for everything - Each item has exactly one correct location
- Person-first for personal records - A spouse's health records go in
12 Spouse, not 50 Health
- Purpose determines area - A bill goes in
27 Bills, not with the service
provider
- JDex is the brain - Notes and decisions live in
00.00 JDex for System
Finding Where Things Go
Before filing, consult:
- Flowchart:
00-09 System/00 System/00.00 JDex for System/flowchart.md
- Full structure:
00-09 System/00 System/00.00 JDex for System/overview.md
Or use your judgment with the filing hierarchy:
- Is it about a specific person? →
10-19 Personal under their folder
- Is it about yourself specifically? →
11 Self
- Otherwise, match by purpose → Areas 20-99
Notes System
Notes about JD items live as markdown files in the JDex:
00-09 System/00 System/00.00 JDex for System/
├── overview.md # System structure documentation
├── flowchart.md # Filing decision tree
├── 31.14.md # Notes about current home
├── 21.10.md # Notes about a bank account
└── ...
Use jd-note to add timestamped entries to these files.
Naming Conventions
Folders:
- Areas:
XX-XX Name (e.g., 20-29 Finances)
- Categories:
XX Name (e.g., 21 Banks)
- Subcategories:
XX.YY Name (e.g., 21.10 Example Bank)
Files:
- Date-prefixed for transient items:
20241227_statement.pdf (YYYYMMDD, no hyphens)
- Descriptive for permanent items:
policy_declaration.pdf
- Statements:
statements/YYYY/MM.pdf or cc_MM.pdf for credit cards
Available Scripts
Scripts are located in ${CLAUDE_SKILL_DIR}/scripts/. Use the full path when invoking:
| Script | Purpose |
|---|
${CLAUDE_SKILL_DIR}/scripts/jd-search.sh <query> | Search for JD folders by name or ID fragment (case-insensitive) |
${CLAUDE_SKILL_DIR}/scripts/jd-list.sh [ID] | List contents of an area, category, or ID |
${CLAUDE_SKILL_DIR}/scripts/jd-tree.sh [-L depth] [ID] | Show directory structure using tree |
${CLAUDE_SKILL_DIR}/scripts/jd-validate.sh <filename> | Check if filename follows conventions |
${CLAUDE_SKILL_DIR}/scripts/jd-mkdir.sh <category> <name> | Create a new subcategory folder (auto-numbers) |
${CLAUDE_SKILL_DIR}/scripts/jd-inbox.sh <source...> | Move files to the inbox (00.01). Shorthand for jd-move <source...> 00.01. |
${CLAUDE_SKILL_DIR}/scripts/jd-move.sh <source...> <ID> [--name <new_name>] [--subdir <path>] | Move files to a JD location. Supports globs (e.g., *.pdf 00.01). --name renames (single source only). --subdir targets a subdirectory within the ID. |
${CLAUDE_SKILL_DIR}/scripts/jd-note.sh [ID] [text] | Add a timestamped note (browse if no ID given) |
${CLAUDE_SKILL_DIR}/scripts/jd-read.sh [ID] [--edit] | Display notes for an ID (browse if no ID given) |
Also available: jd <query> for navigation (in ~/bin/).
Some bash commands, like mv are not allowed by your settings in the folder,
so use the scripts.
Interactive Features
When run by a human (not an agent), these commands have interactive modes:
jd-note (no args) - Hierarchical browse (Area → Category → ID), then opens editorjd-note <ID> (without text) - Opens editor to write a notejd-read (no args) - Hierarchical browse (Area → Category → ID), then displays notesjd-read --edit (no args) - Hierarchical browse, then opens editorjd-read <ID> --edit - Opens the note file for editing
All properly handle TTY redirection for compatibility with any editor.
Agent Usage (--porcelain)
All scripts support a --porcelain flag for machine-readable output:
${CLAUDE_SKILL_DIR}/scripts/jd-search.sh bank --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-inbox.sh scan.pdf --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-list.sh 21 --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-tree.sh -L3 --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-mkdir.sh 21 "Name" --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-move.sh file.pdf 21.10 --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-move.sh *.pdf 00.01 --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-move.sh file.pdf 21.10 --name renamed.pdf --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-move.sh file.pdf 91.10 --subdir Bolos/covers --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-note.sh 21.10 "text" --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-read.sh 21.10 --porcelain
${CLAUDE_SKILL_DIR}/scripts/jd-validate.sh file.pdf --porcelain
When using these scripts as an agent:
- Always use
--porcelain for reliable parsing
- Paths are absolute and suitable for further operations
- Errors go to stderr with exit code 1
jd-note requires text argument in agent mode (no editor)jd-read --edit is not available in agent mode (requires TTY)- All scripts auto-detect agent mode when stdout/stdin are not TTYs
Safety Rules
- Scripts will refuse to overwrite existing files
- Scripts validate paths before operations
- Always confirm destructive operations with the user
- When uncertain about filing location, ask rather than guess
Gotchas
- Person-first filing: A spouse's medical records go in
12 Spouse, not
50 Health. A child's school docs go in 13 Kids, not 40 Education.
Always check if the item belongs to a specific person before filing by topic.
- Purpose over provider: A utility bill goes in
27 Bills, not with the
utility company in 80 Services. File by purpose, not by the entity that
sent it.
- Scan-date filenames are never final: Files in the inbox (
00.01) are
named by scan date (e.g., 20260127.pdf). Always rename before filing.
- JDex notes vs. filed documents: Notes about a JD item go in the JDex
(
00.00). The actual documents go in the item's folder.
--porcelain is required in agent mode: Without it, scripts may output
colored/truncated paths that are unreliable for further operations.- ScanSnap PDFs may be upside down: When the ScanSnap scans directly to the
NAS, pages often come out rotated 180°. After filing, check orientation and
fix with
pdftk input.pdf cat 1-endsouth output rotated.pdf.
Filing Inbox Documents
Files in the inbox (00.01) are typically scanned documents named by scan date
(e.g., 20260127.pdf). When filing them:
- Read the file to determine what it is
- Decide where it goes using the flowchart and overview
ls the target directory to learn its naming conventions- Choose the final filename to match the existing pattern --- see
${CLAUDE_SKILL_DIR}/references/NAMING.md
- Move and rename in one step using
jd-move <file> <ID> --name <new_name>
The scan-date filename is never the final name. Always rename during the move.
When to Explore
If you need current structure details not covered here, read:
overview.md in the JDex for full category breakdownflowchart.md in the JDex for filing decisions- Use
${CLAUDE_SKILL_DIR}/scripts/jd-list.sh to see what exists in a location
References
For more detailed guidance, use the Read tool to load:
${CLAUDE_SKILL_DIR}/references/FILING-GUIDE.md - Detailed filing decisions and examples${CLAUDE_SKILL_DIR}/references/NAMING.md - File and folder naming conventions
