mbailey · mbailey · Dec 27, 2025 · Dec 27, 2025
diff --git a/SKILL.md b/SKILL.md
@@ -9,14 +9,7 @@ description: Package management for modular code organization. This skill should
 
 Metool (mt) organizes code through packages - self-contained units with scripts, functions, configuration, and documentation. Packages are organized in modules and installed via GNU Stow symlinks. From shell utilities to complete applications, all code follows the same structure.
 
-## When to Use This Skill
-
-Use this skill when:
-- Creating new metool packages
-- Installing or modifying metool packages
-- Working with metool commands (install, cd, edit, etc.)
-- Setting up configuration files or dotfiles via metool
-- Creating or updating Claude Code skills for metool packages
+See [README.md](README.md) for installation and getting started.
 
 ## Quick Reference
 
@@ -25,16 +18,15 @@ Use this skill when:
 ```
 package-name/
 ├── README.md        # Required
-├── SKILL.md         # Optional (enables AI assistance)
-├── bin/             # Executables (symlinked to ~/.metool/bin)
-├── shell/           # Functions, aliases, completions
-├── config/          # Dotfiles (use dot- prefix)
-├── lib/             # Library functions
-├── libexec/         # Helper scripts (not in PATH)
-└── docs/            # Additional documentation
+├── SKILL.md         # Optional (AI assistance)
+├── bin/             # Executables → ~/.metool/bin/
+├── shell/           # Functions, aliases → sourced on startup
+├── config/          # Dotfiles (dot- prefix) → ~/
+├── lib/             # Library functions (not symlinked)
+└── libexec/         # Helper scripts (not in PATH)
 ```
 
-For complete conventions, see @docs/conventions/package-structure.md
+See [docs/packages/structure.md](docs/packages/structure.md) for conventions.
 
 ### Essential Commands
 
@@ -43,219 +35,72 @@ mt package add module/package    # Add to working set
 mt package install package-name  # Install (create symlinks)
 mt cd package-name               # Navigate to package
 mt edit function-name            # Edit a function/script
-mt reload                        # Reload after changes
-```
-
-For all commands, see @docs/reference/commands/README.md
-
-### How mt Works
-
-The `mt` command is a shell function (not a binary), which enables features like `mt cd` that change your current directory. Most functionality works through the function.
-
-**Fallback binary**: When the shell function isn't available (e.g., calling from scripts, cron, or non-bash shells), use `bin/mt` directly. This binary wrapper sources the function and executes commands, but some features like directory changing won't affect the parent shell.
-
-## Creating a Package
-
-### Step 1: Create Structure
-
-```bash
-mkdir -p package-name/{bin,shell,config,lib}
-```
-
-### Step 2: Create README.md (Required)
-
-```markdown
-# Package Name
-
-Brief description
-
-## Installation
-
-\`\`\`bash
-mt package add module/package-name
-mt package install package-name
-\`\`\`
-
-## Components
-
-- `bin/tool-name` - Main tool
-- `shell/functions` - Helper functions
-
-## Usage
-
-[Usage examples]
-```
-
-### Step 3: Add Components
-
-**Executables (bin/):**
-```bash
-cat > package-name/bin/tool-name << 'EOF'
-#!/usr/bin/env bash
-# Tool description
-EOF
-chmod +x package-name/bin/tool-name
-```
-
-**Shell Functions (shell/):**
-- `shell/functions` - Shell functions
-- `shell/aliases` - Command aliases
-- `shell/completions/` - Bash tab completion
-- `shell/environment` - Environment exports
-- `shell/path` - PATH modifications
-
-**Dotfiles (config/):**
-Use `dot-` prefix: `config/dot-bashrc` → `~/.bashrc`
-
-See @docs/conventions/package-structure.md for full details.
-
-### Step 4: Install
-
-```bash
-mt package add module/package-name
-mt package install package-name
+mt reload                        # Reload shell configuration
 ```
 
-## Python Scripts
+See [docs/commands/README.md](docs/commands/README.md) for full reference.
 
-Use uv with PEP 723 inline script metadata:
-
-```python
-#!/usr/bin/env python
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["requests", "click"]
-# ///
-
-import requests
-import click
-# Script implementation
-```
-
-Scripts in `bin/` should have no `.py` extension.
-
-## Service Packages
-
-For packages managing systemd/launchd services, use the service package template.
-
-See @docs/templates/service-package/README.md for:
-- Cross-platform service management (Linux/macOS)
-- Standard subcommands: install, start, stop, restart, status, logs
-- Version detection and monitoring
-- Complete shell aliases pattern
+## Workflows
 
-## Package Promotion
+### Creating a Package
 
-Promote packages from development to public modules safely.
+Create directory structure, add README.md, implement components, install.
 
-### Compare Packages Between Modules
+See [docs/packages/creation.md](docs/packages/creation.md) for step-by-step guide.
 
 ```bash
-# See what differs
-mt package diff tmux dev pub
-
-# Show detailed content differences
-mt package diff tmux dev pub --content
-
-# Quiet mode for scripting
-mt package diff tmux dev pub --quiet
+mt package new my-package /path/to/module  # Create from template
 ```
 
-### Promotion Workflow
+### Adding a Skill to a Package
 
-1. **Compare** - `mt package diff <package> dev pub`
-2. **Review** - Check for sensitive content (secrets, internal paths)
-3. **Promote** - Copy approved files to target module
-4. **Commit** - Commit changes in target module
+Create SKILL.md in package root with required frontmatter.
 
-See `docs/guides/package-promotion.md` for detailed workflow.
+See [docs/skills/README.md](docs/skills/README.md) for skill creation.
 
-## Claude Code Skills
+### Service Packages
 
-Packages can include a `SKILL.md` file to enable AI assistance. This creates human-AI collaborative infrastructure where:
-- Humans get CLI tools, shell functions, and documentation
-- AI gets procedural knowledge, workflows, and tool references
+For systemd/launchd services, use the service package template.
 
-### SKILL.md Structure
-
-```markdown
----
-name: package-name
-description: Brief explanation. This skill should be used when [scenarios].
----
+See [docs/services/README.md](docs/services/README.md) for service management.
 
-# Package Name
+### Package Promotion
 
-## Overview
-[What this skill enables]
+Move packages between modules (dev → public).
 
-## Workflows
-[Step-by-step procedures with tool references]
-```
-
-### Key Points
-
-- Use third-person in description ("This skill should be used when...")
-- Keep under 5k words; move details to docs/
-- Reference package tools by command name (they're in PATH after install)
-- Focus on procedural knowledge Claude cannot infer
-
-See @docs/conventions/package-structure.md#skillmd-optional for frontmatter requirements and installation mechanism.
-
-### Creating a Package with Skill
+See [docs/packages/promotion.md](docs/packages/promotion.md) for workflow.
 
 ```bash
-mt package new my-package /path/to/module
+mt package diff package-name dev pub  # Compare versions
 ```
 
-Creates package from template including `SKILL.md.example`. Rename to `SKILL.md` to activate.
-
 ## Discovering Packages
 
 ```bash
-mt module list                    # List modules
+mt module list                    # List modules in working set
 mt package list                   # List all packages
 mt package list | grep -w git     # Find specific package
 ```
 
-**Context-efficient workflow**: Use grep to filter rather than loading full list.
-
-## Checking Dependencies
-
-```bash
-if ! command -v required-tool >/dev/null; then
-  echo "Error: required-tool is needed but not installed" >&2
-  exit 1
-fi
-```
-
-For metool package dependencies:
-```bash
-if ! command -v other-tool >/dev/null; then
-  echo "Error: other-tool from other-package is required" >&2
-  echo "Install with: mt package add module/other-package && mt package install other-package" >&2
-  exit 1
-fi
-```
-
 ## Troubleshooting
 
-### Conflicts During Installation
-When config files conflict, the command prompts to remove existing files and retry.
+### Installation Conflicts
+
+When config files conflict, remove existing files when prompted.
 
 ### Prerequisites
+
 ```bash
 mt deps              # Check dependencies
-mt deps --install    # Auto-install on macOS (requires Homebrew)
+mt deps --install    # Auto-install on macOS
 ```
 
 Requires: GNU coreutils, GNU Stow 2.4.0+
 
-## Documentation Resources
+## Documentation
 
-- @docs/conventions/package-structure.md - Complete package conventions
-- @docs/conventions/shell-scripting.md - Shell scripting best practices
-- @docs/reference/commands/README.md - Command reference
-- @docs/templates/service-package/README.md - Service package template
-- @docs/guides/GETTING-STARTED.md - Getting started guide
-- @docs/guides/package-promotion.md - Package promotion workflow
+- [docs/getting-started.md](docs/getting-started.md) - Installation and setup
+- [docs/packages/README.md](docs/packages/README.md) - Package management
+- [docs/skills/README.md](docs/skills/README.md) - Claude Code skills
+- [docs/services/README.md](docs/services/README.md) - Service packages
+- [docs/commands/README.md](docs/commands/README.md) - Command reference
diff --git a/docs/reference/commands/README.md → docs/commands/README.md b/docs/reference/commands/README.md → docs/commands/README.md
diff --git a/docs/reference/commands/cd.md → docs/commands/cd.md b/docs/reference/commands/cd.md → docs/commands/cd.md
diff --git a/docs/reference/commands/clone.md → docs/commands/clone.md b/docs/reference/commands/clone.md → docs/commands/clone.md
diff --git a/docs/reference/commands/components.md → docs/commands/components.md b/docs/reference/commands/components.md → docs/commands/components.md
diff --git a/docs/reference/commands/deps.md → docs/commands/deps.md b/docs/reference/commands/deps.md → docs/commands/deps.md
diff --git a/docs/reference/commands/disable.md → docs/commands/disable.md b/docs/reference/commands/disable.md → docs/commands/disable.md
diff --git a/docs/reference/commands/edit.md → docs/commands/edit.md b/docs/reference/commands/edit.md → docs/commands/edit.md
diff --git a/docs/reference/commands/enable.md → docs/commands/enable.md b/docs/reference/commands/enable.md → docs/commands/enable.md
diff --git a/docs/reference/commands/git.md → docs/commands/git.md b/docs/reference/commands/git.md → docs/commands/git.md
diff --git a/docs/reference/commands/install.md → docs/commands/install.md b/docs/reference/commands/install.md → docs/commands/install.md
diff --git a/docs/reference/commands/modules.md → docs/commands/modules.md b/docs/reference/commands/modules.md → docs/commands/modules.md
diff --git a/docs/reference/commands/packages.md → docs/commands/packages.md b/docs/reference/commands/packages.md → docs/commands/packages.md
diff --git a/docs/reference/commands/pull.md → docs/commands/pull.md b/docs/reference/commands/pull.md → docs/commands/pull.md
diff --git a/docs/reference/commands/push.md → docs/commands/push.md b/docs/reference/commands/push.md → docs/commands/push.md
diff --git a/docs/reference/commands/reload.md → docs/commands/reload.md b/docs/reference/commands/reload.md → docs/commands/reload.md
diff --git a/docs/reference/commands/repos.md → docs/commands/repos.md b/docs/reference/commands/repos.md → docs/commands/repos.md
diff --git a/docs/reference/commands/update.md → docs/commands/update.md b/docs/reference/commands/update.md → docs/commands/update.md
diff --git a/docs/conventions/README.md b/docs/conventions/README.md
diff --git a/docs/conventions/documentation/README.md → docs/development/documentation/README.md b/docs/conventions/documentation/README.md → docs/development/documentation/README.md
diff --git a/...onventions/documentation/command-usage.md → ...evelopment/documentation/command-usage.md b/...onventions/documentation/command-usage.md → ...evelopment/documentation/command-usage.md
diff --git a/.../documentation/docs-structure-concepts.md → .../documentation/docs-structure-concepts.md b/.../documentation/docs-structure-concepts.md → .../documentation/docs-structure-concepts.md
diff --git a/...nventions/documentation/docs-structure.md → ...velopment/documentation/docs-structure.md b/...nventions/documentation/docs-structure.md → ...velopment/documentation/docs-structure.md
diff --git a/...conventions/documentation/readme-guide.md → ...development/documentation/readme-guide.md b/...conventions/documentation/readme-guide.md → ...development/documentation/readme-guide.md
diff --git a/...tions/documentation/root-documentation.md → ...pment/documentation/root-documentation.md b/...tions/documentation/root-documentation.md → ...pment/documentation/root-documentation.md
diff --git a/...onventions/documentation/writing-style.md → ...evelopment/documentation/writing-style.md b/...onventions/documentation/writing-style.md → ...evelopment/documentation/writing-style.md
diff --git a/docs/conventions/shell-scripting.md → docs/development/shell-scripting.md b/docs/conventions/shell-scripting.md → docs/development/shell-scripting.md
diff --git a/docs/conventions/testing.md → docs/development/testing.md b/docs/conventions/testing.md → docs/development/testing.md
diff --git a/docs/guides/GETTING-STARTED.md → docs/getting-started.md b/docs/guides/GETTING-STARTED.md → docs/getting-started.md
diff --git a/docs/guides/README.md b/docs/guides/README.md
diff --git a/docs/packages/README.md b/docs/packages/README.md
@@ -0,0 +1,42 @@
+# Packages
+
+Metool packages are self-contained units of functionality that organize scripts, functions, configuration files, and documentation.
+
+## Contents
+
+- [structure.md](structure.md) - Package directory layout and conventions
+- [symlinks.md](symlinks.md) - How GNU Stow creates symlinks during installation
+- [creation.md](creation.md) - Step-by-step guide to creating a new package
+- [python.md](python.md) - Python script conventions (uv, PEP 723)
+- [naming.md](naming.md) - Package and script naming conventions
+- [promotion.md](promotion.md) - Moving packages between modules
+
+## Quick Reference
+
+### Package Structure
+
+```
+package-name/
+├── README.md        # Documentation (required)
+├── SKILL.md         # Claude Code skill (optional)
+├── bin/             # Executables → ~/.metool/bin/
+├── shell/           # Functions, aliases → ~/.metool/shell/
+├── config/          # Dotfiles → ~/
+├── lib/             # Library functions (not symlinked)
+├── libexec/         # Helper scripts (not in PATH)
+└── docs/            # Additional documentation
+```
+
+### Essential Commands
+
+```bash
+mt package add module/package    # Add to working set
+mt package install package-name  # Install (create symlinks)
+mt cd package-name               # Navigate to package
+```
+
+## See Also
+
+- [docs/skills/README.md](../skills/README.md) - Adding AI assistance to packages
+- [docs/services/README.md](../services/README.md) - Service management packages
+- [docs/commands/README.md](../commands/README.md) - Full command reference