Agent skill

jd-docs

Scaffold, validate, and maintain Johnny.Decimal documentation structure for software projects. Use when user mentions "Johnny Decimal", "J.D docs", "docs structure", "organize docs", "documentation layout", "scaffold docs", "docs migration", "generate index", "docs index", "add area", "classify docs", "move doc", editing files in numbered directories (00-*, 10-*, 20-*), or discussing documentation organization.

View SKILL.md on GitHub Repository
Stars 9
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/joaquimscosta/arkhe-claude-plugins/tree/main/plugins/doc/skills/jd-docs

SKILL.md

Johnny.Decimal Documentation

Scaffold, validate, and maintain Johnny.Decimal documentation structure with sensible defaults and per-project customization.

Quick Start

bash
# Scaffold a new structure
uv run scripts/jd_init.py --dry-run   # Preview first
uv run scripts/jd_init.py             # Create docs/ with defaults
uv run scripts/jd_init.py --diataxis  # Include Diataxis areas (41-44)

# Validate existing structure
uv run scripts/jd_validate.py --dir docs

# Regenerate README index
uv run scripts/jd_index.py --dir docs

# Day-2: Add a new area
uv run scripts/jd_add_area.py --prefix 40 --name operations --dry-run

# Day-2: Classify unorganized files
uv run scripts/jd_classify.py docs/*.md
uv run scripts/jd_classify.py docs/*.md --diataxis  # With quadrant info

# Day-2: Move a file to an area
uv run scripts/jd_add.py docs/roadmap.md 00 --dry-run

See WORKFLOW.md for the full methodology.

Capabilities

  • Scaffolding (jd_init.py) — Create J.D directory tree with README templates; supports --product for monorepo sub-trees, --init-config to generate .jd-config.json, and --diataxis to include Diataxis quadrant areas (41-44)
  • Validation (jd_validate.py) — Check NN-kebab-case naming, detect orphan files, verify README presence per area; --strict for CI enforcement
  • Index generation (jd_index.py) — Generate/update root README with table or tree index; preserves custom content via <!-- JD:INDEX:START/END --> markers
  • Migration (Claude-driven) — Classify flat docs into J.D areas using naming heuristics, present a move plan, execute interactively

Day-2 Operations

  • Add area (jd_add_area.py) — Create a new J.D area with prefix, name, README stub, config update, and auto re-index
  • Classify (jd_classify.py) — Classify files into areas using keyword heuristics with confidence scoring (high/medium/low); --diataxis adds Diataxis quadrant column, --diataxis-move routes files to quadrant areas (41-44)
  • Add/move file (jd_add.py) — Move a file to an area with auto-normalized kebab-case naming and cross-reference detection

Default Area Scheme

Prefix Name Purpose
00- getting-started Onboarding, setup, quick start, MVP
10- product Specs, features, roadmap, design, branding
20- architecture Tech decisions, system design, integration
30- research Spikes, investigations, reference material
90- archive Historical/deprecated docs

Gap at 40-80 reserved for per-project customization (e.g., 40-operations).

With --diataxis, areas 41-44 are added for Diataxis quadrants:

| 41- | tutorials | Tutorials — step-by-step lessons (Diataxis) | | 42- | how-to | How-to guides — practical tasks (Diataxis) | | 43- | reference | Reference — technical descriptions (Diataxis) | | 44- | explanation | Explanation — conceptual discussions (Diataxis) |

Config File (.jd-config.json)

Optional per-project override at project root:

json
{
  "version": 1,
  "root": "docs",
  "areas": { "00": "getting-started", "10": "product", "20": "architecture", "30": "research", "90": "archive" },
  "products": [],
  "ignore": ["adr", "*.pdf"],
  "readme_format": "table"
}

Create with uv run scripts/jd_init.py --init-config. All fields have sensible defaults.

Common Issues

Issue Fix
uv not found curl -LsSf https://astral.sh/uv/install.sh | sh or run with python3 scripts/jd_init.py
Orphan files in validation Move to area dir, or add to "ignore" in .jd-config.json
Index appended at wrong position Move <!-- JD:INDEX:START/END --> markers to desired location after first run
Low confidence on all files Expand keywords in config or use Claude-driven classification

See TROUBLESHOOTING.md for all error scenarios.

References

  • WORKFLOW.md — Full methodology (discovery, config, scaffold, validate, index, migrate, day-2)
  • EXAMPLES.md — Real-world examples for all operations
  • TROUBLESHOOTING.md — Error handling and debugging tips

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

joaquimscosta/arkhe-claude-plugins

Skill Name

What this skill does. Use when user mentions "keyword1", "keyword2", or "keyword3". Keep under 1,024 characters and include specific trigger keywords.

9 1
Explore
joaquimscosta/arkhe-claude-plugins

plugin-release-checker

9 1
Explore
joaquimscosta/arkhe-claude-plugins

skill-validator

Validate skills against Anthropic best practices for frontmatter, structure, content, file organization, hooks, MCP, and security (62 rules in 8 categories). Use when creating new skills, updating existing skills, before publishing skills, reviewing skill quality, or when user mentions "validate skill", "check skill", "skill best practices", "skill review", or "lint skill".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

sync-docs

Sync official Anthropic documentation and analyze impact on project components. Runs docs/reference/update-claude-docs.sh, computes diffs, and reports impacts on the skill validator, plugins, and project documentation. Use when user mentions "sync docs", "update reference docs", "refresh docs", or "check doc changes".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

research-frontmatter

Enforce standard YAML frontmatter on research documents in docs/research/. Use when creating, editing, or promoting research files, when user mentions "research metadata", "research frontmatter", or "research staleness".

9 1
Explore
joaquimscosta/arkhe-claude-plugins

deep-research

Deep research on technical topics using EXA tools with intelligent two-tier caching. Use when user asks to research a topic, investigate best practices, look up information, find patterns, or explore architectures. Also invoked by /research command. Triggers: "research", "look up", "investigate", "deep dive", "find information about", "what are best practices for", "how do others implement".

9 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results