diff --git a/SKILL.md b/SKILL.md
index 71307dd..8beb48a 100644
--- 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 b/docs/commands/README.md
similarity index 100%
rename from docs/reference/commands/README.md
rename to docs/commands/README.md
diff --git a/docs/reference/commands/cd.md b/docs/commands/cd.md
similarity index 100%
rename from docs/reference/commands/cd.md
rename to docs/commands/cd.md
diff --git a/docs/reference/commands/clone.md b/docs/commands/clone.md
similarity index 100%
rename from docs/reference/commands/clone.md
rename to docs/commands/clone.md
diff --git a/docs/reference/commands/components.md b/docs/commands/components.md
similarity index 100%
rename from docs/reference/commands/components.md
rename to docs/commands/components.md
diff --git a/docs/reference/commands/deps.md b/docs/commands/deps.md
similarity index 100%
rename from docs/reference/commands/deps.md
rename to docs/commands/deps.md
diff --git a/docs/reference/commands/disable.md b/docs/commands/disable.md
similarity index 100%
rename from docs/reference/commands/disable.md
rename to docs/commands/disable.md
diff --git a/docs/reference/commands/edit.md b/docs/commands/edit.md
similarity index 100%
rename from docs/reference/commands/edit.md
rename to docs/commands/edit.md
diff --git a/docs/reference/commands/enable.md b/docs/commands/enable.md
similarity index 100%
rename from docs/reference/commands/enable.md
rename to docs/commands/enable.md
diff --git a/docs/reference/commands/git.md b/docs/commands/git.md
similarity index 100%
rename from docs/reference/commands/git.md
rename to docs/commands/git.md
diff --git a/docs/reference/commands/install.md b/docs/commands/install.md
similarity index 100%
rename from docs/reference/commands/install.md
rename to docs/commands/install.md
diff --git a/docs/reference/commands/modules.md b/docs/commands/modules.md
similarity index 100%
rename from docs/reference/commands/modules.md
rename to docs/commands/modules.md
diff --git a/docs/reference/commands/packages.md b/docs/commands/packages.md
similarity index 100%
rename from docs/reference/commands/packages.md
rename to docs/commands/packages.md
diff --git a/docs/reference/commands/pull.md b/docs/commands/pull.md
similarity index 100%
rename from docs/reference/commands/pull.md
rename to docs/commands/pull.md
diff --git a/docs/reference/commands/push.md b/docs/commands/push.md
similarity index 100%
rename from docs/reference/commands/push.md
rename to docs/commands/push.md
diff --git a/docs/reference/commands/reload.md b/docs/commands/reload.md
similarity index 100%
rename from docs/reference/commands/reload.md
rename to docs/commands/reload.md
diff --git a/docs/reference/commands/repos.md b/docs/commands/repos.md
similarity index 100%
rename from docs/reference/commands/repos.md
rename to docs/commands/repos.md
diff --git a/docs/reference/commands/update.md b/docs/commands/update.md
similarity index 100%
rename from docs/reference/commands/update.md
rename to docs/commands/update.md
diff --git a/docs/conventions/README.md b/docs/conventions/README.md
deleted file mode 100644
index 5497f82..0000000
--- a/docs/conventions/README.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Metool Conventions
-
-Coding conventions and best practices for development of metool itself, as well as metool modules and packages.
-
-## Overview
-
-These conventions ensure consistency across metool and metool packages, making it easier for contributors and AI agents to understand and extend the project.
-
-## Conventions
-
-- [Shell Scripting](shell-scripting.md) - Bash coding standards and patterns
-- [Testing](testing.md) - How to write and organize tests
-- [Documentation](documentation/README.md) - Documentation standards and structure
-- [Package Structure](package-structure.md) - How to structure metool packages
-- [Symlinks](symlinks.md) - Symlink handling conventions
-
-## General Principles
-
-1. **Simplicity First** - Choose the simplest solution that works
-2. **Consistency** - Follow existing patterns in the codebase
-3. **Portability** - Support Linux, macOS, and WSL
-4. **Testability** - Write code that's easy to test
-5. **Documentation** - Document complex logic and user-facing features
-
-## Contributing
-
-When adding new features or modifying existing ones:
-
-1. Follow the conventions outlined in these documents
-2. Update tests to cover your changes
-3. Update documentation as needed
-4. Ensure all tests pass before submitting
diff --git a/docs/conventions/documentation/README.md b/docs/development/documentation/README.md
similarity index 100%
rename from docs/conventions/documentation/README.md
rename to docs/development/documentation/README.md
diff --git a/docs/conventions/documentation/command-usage.md b/docs/development/documentation/command-usage.md
similarity index 100%
rename from docs/conventions/documentation/command-usage.md
rename to docs/development/documentation/command-usage.md
diff --git a/docs/conventions/documentation/docs-structure-concepts.md b/docs/development/documentation/docs-structure-concepts.md
similarity index 100%
rename from docs/conventions/documentation/docs-structure-concepts.md
rename to docs/development/documentation/docs-structure-concepts.md
diff --git a/docs/conventions/documentation/docs-structure.md b/docs/development/documentation/docs-structure.md
similarity index 100%
rename from docs/conventions/documentation/docs-structure.md
rename to docs/development/documentation/docs-structure.md
diff --git a/docs/conventions/documentation/readme-guide.md b/docs/development/documentation/readme-guide.md
similarity index 100%
rename from docs/conventions/documentation/readme-guide.md
rename to docs/development/documentation/readme-guide.md
diff --git a/docs/conventions/documentation/root-documentation.md b/docs/development/documentation/root-documentation.md
similarity index 100%
rename from docs/conventions/documentation/root-documentation.md
rename to docs/development/documentation/root-documentation.md
diff --git a/docs/conventions/documentation/writing-style.md b/docs/development/documentation/writing-style.md
similarity index 100%
rename from docs/conventions/documentation/writing-style.md
rename to docs/development/documentation/writing-style.md
diff --git a/docs/conventions/shell-scripting.md b/docs/development/shell-scripting.md
similarity index 100%
rename from docs/conventions/shell-scripting.md
rename to docs/development/shell-scripting.md
diff --git a/docs/conventions/testing.md b/docs/development/testing.md
similarity index 100%
rename from docs/conventions/testing.md
rename to docs/development/testing.md
diff --git a/docs/guides/GETTING-STARTED.md b/docs/getting-started.md
similarity index 100%
rename from docs/guides/GETTING-STARTED.md
rename to docs/getting-started.md
diff --git a/docs/guides/README.md b/docs/guides/README.md
deleted file mode 100644
index 9d7629b..0000000
--- a/docs/guides/README.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Metool Guides
-
-Practical guides for using metool effectively.
-
-## Available Guides
-
-- [Repository Management](repository-management.md) - Capture and recreate your development environment using repos.txt manifests
-
-## Guide Categories
-
-### Development Workflow
-- Repository Management - Managing git repositories across machines
-
-### Package Development
-- (Coming soon) Creating Packages - How to create metool packages
-- (Coming soon) Service Packages - Building packages that manage services
-
-### System Setup
-- (Coming soon) New Machine Setup - Complete guide to setting up metool on a new system
-- (Coming soon) Multi-User Setup - Sharing metool packages across users
-
-## Contributing
-
-To add a new guide:
-1. Create a markdown file in this directory
-2. Update this README with a link
-3. Follow the existing guide structure
-4. Include practical examples
\ No newline at end of file
diff --git a/docs/packages/README.md b/docs/packages/README.md
new file mode 100644
index 0000000..4a91db4
--- /dev/null
+++ 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
diff --git a/docs/packages/creation.md b/docs/packages/creation.md
new file mode 100644
index 0000000..9743439
--- /dev/null
+++ b/docs/packages/creation.md
@@ -0,0 +1,134 @@
+# Creating a Package
+
+Step-by-step guide to creating a new metool package.
+
+## Step 1: Create Directory Structure
+
+```bash
+mkdir -p package-name/{bin,shell,config,lib}
+```
+
+## Step 2: Create README.md (Required)
+
+Every package must have a README.md:
+
+```markdown
+# Package Name
+
+Brief description of what this package provides
+
+## Installation
+
+\`\`\`bash
+mt package add module/package-name
+mt package install package-name
+\`\`\`
+
+## Components
+
+- `bin/tool-name` - Main tool for doing X
+- `shell/functions` - Helper functions for Y
+- `config/dot-toolrc` - Configuration file
+
+## Usage
+
+[Usage examples]
+
+## Requirements
+
+- bash 4.0+
+- other dependencies
+```
+
+## Step 3: Add Components
+
+### Executables (bin/)
+
+```bash
+cat > package-name/bin/tool-name << 'EOF'
+#!/usr/bin/env bash
+# Tool description
+set -euo pipefail
+
+# Implementation
+EOF
+
+chmod +x package-name/bin/tool-name
+```
+
+Requirements:
+- Must be executable (`chmod +x`)
+- Should have shebang line
+- Names should be descriptive and unique
+
+### Shell Functions (shell/)
+
+```bash
+cat > package-name/shell/functions << 'EOF'
+# Function description
+function_name() {
+    # Implementation
+}
+EOF
+```
+
+Shell directory structure:
+- `shell/functions` - Shell functions
+- `shell/aliases` - Command aliases
+- `shell/completions/` - Bash tab completion
+- `shell/environment` - Environment variable exports
+- `shell/path` - PATH modifications
+
+### Configuration Files (config/)
+
+Use `dot-` prefix for dotfiles:
+
+```bash
+mkdir -p package-name/config
+cat > package-name/config/dot-toolrc << 'EOF'
+# Configuration
+EOF
+```
+
+The `dot-` prefix becomes `.` when installed:
+- `config/dot-bashrc` → `~/.bashrc`
+- `config/dot-config/tool/` → `~/.config/tool/`
+
+## Step 4: Install the Package
+
+```bash
+# Add to working set
+mt package add module/package-name
+
+# Install (create symlinks)
+mt package install package-name
+
+# Reload shell to pick up new functions
+mt reload
+```
+
+## Adding a Skill (Optional)
+
+To enable AI assistance, create a `SKILL.md` file:
+
+```bash
+mt package new my-package /path/to/module
+```
+
+This creates a package from template including `SKILL.md.example`. Rename to `SKILL.md` to activate.
+
+See [docs/skills/README.md](../skills/README.md) for skill creation details.
+
+## Best Practices
+
+1. **One Purpose** - Each package should have a clear, focused purpose
+2. **Self-Contained** - Packages should work independently
+3. **Well-Documented** - Include README and inline documentation
+4. **Tested** - Test packages before installing
+5. **Dependencies** - Document and check for dependencies
+
+## See Also
+
+- [structure.md](structure.md) - Package directory conventions
+- [naming.md](naming.md) - Naming conventions
+- [python.md](python.md) - Python script conventions
diff --git a/docs/packages/naming.md b/docs/packages/naming.md
new file mode 100644
index 0000000..3aebd4b
--- /dev/null
+++ b/docs/packages/naming.md
@@ -0,0 +1,81 @@
+# Naming Conventions
+
+Naming conventions for metool packages and scripts.
+
+## Package Names
+
+- Use **lowercase with hyphens**
+- Be descriptive but concise
+- Avoid generic names
+
+### Good Examples
+
+- `git-tools` - Clear purpose
+- `docker-helpers` - Descriptive
+- `aws-scripts` - Specific domain
+
+### Bad Examples
+
+- `utils` - Too generic
+- `MyTools` - Wrong case
+- `misc` - Not descriptive
+- `stuff` - Meaningless
+
+## Script Names
+
+- Use **lowercase with hyphens**
+- Include package prefix if needed for clarity
+- Make purpose obvious from name
+
+### Examples
+
+- `git-branch-clean` - Action is clear
+- `docker-cleanup` - Domain + action
+- `aws-ec2-list` - Service + resource + action
+
+## Function Names
+
+For shell functions in `shell/functions`:
+
+- Use **lowercase with underscores** for internal functions
+- Prefix with package name to avoid conflicts
+
+```bash
+# Good
+git_tools_cleanup_branches() { ... }
+
+# Avoid (might conflict)
+cleanup_branches() { ... }
+```
+
+## Alias Names
+
+Keep aliases short but memorable:
+
+```bash
+# In shell/aliases
+alias gbc='git-branch-clean'
+alias dcl='docker-cleanup'
+```
+
+## Configuration Files
+
+Use `dot-` prefix in `config/`:
+
+- `dot-gitconfig` → `~/.gitconfig`
+- `dot-bashrc` → `~/.bashrc`
+- `dot-config/tool/` → `~/.config/tool/`
+
+## Module Names
+
+Modules group related packages:
+
+- `metool-packages` - Public packages
+- `metool-packages-dev` - Development packages
+- `metool-packages-personal` - Personal packages
+- `metool-packages-work` - Work-specific packages
+
+## See Also
+
+- [structure.md](structure.md) - Package structure conventions
+- [creation.md](creation.md) - Creating packages
diff --git a/docs/guides/package-promotion.md b/docs/packages/promotion.md
similarity index 100%
rename from docs/guides/package-promotion.md
rename to docs/packages/promotion.md
diff --git a/docs/packages/python.md b/docs/packages/python.md
new file mode 100644
index 0000000..edfc05d
--- /dev/null
+++ b/docs/packages/python.md
@@ -0,0 +1,79 @@
+# Python Scripts in Metool Packages
+
+Conventions for Python scripts in metool packages.
+
+## Package Manager
+
+Use **uv** as the package manager for Python scripts.
+
+## Inline Script Metadata (PEP 723)
+
+Use inline script metadata to declare dependencies:
+
+```python
+#!/usr/bin/env python
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["requests", "click"]
+# ///
+
+import requests
+import click
+
+@click.command()
+def main():
+    # Script implementation
+    pass
+
+if __name__ == "__main__":
+    main()
+```
+
+## File Naming
+
+Scripts in `bin/` should have **no `.py` extension**:
+
+```
+package-name/
+└── bin/
+    ├── my-tool           # ✓ Correct
+    └── my-tool.py        # ✗ Avoid
+```
+
+This keeps commands clean:
+```bash
+my-tool --help    # ✓ Clean
+my-tool.py --help # ✗ Awkward
+```
+
+## Running Scripts
+
+With uv, scripts run directly:
+
+```bash
+# uv handles dependency installation automatically
+./bin/my-tool
+
+# Or with explicit uv
+uv run bin/my-tool
+```
+
+## Virtual Environments
+
+For packages with many Python scripts sharing dependencies, consider a `pyproject.toml`:
+
+```
+package-name/
+├── pyproject.toml
+├── bin/
+│   ├── tool-one
+│   └── tool-two
+└── src/
+    └── package_name/
+        └── __init__.py
+```
+
+## See Also
+
+- [creation.md](creation.md) - Creating packages
+- [structure.md](structure.md) - Package structure conventions
diff --git a/docs/conventions/package-structure.md b/docs/packages/structure.md
similarity index 100%
rename from docs/conventions/package-structure.md
rename to docs/packages/structure.md
diff --git a/docs/conventions/symlinks.md b/docs/packages/symlinks.md
similarity index 100%
rename from docs/conventions/symlinks.md
rename to docs/packages/symlinks.md
diff --git a/docs/guides/repository-management.md b/docs/repositories.md
similarity index 100%
rename from docs/guides/repository-management.md
rename to docs/repositories.md
diff --git a/docs/services/README.md b/docs/services/README.md
new file mode 100644
index 0000000..b8f0250
--- /dev/null
+++ b/docs/services/README.md
@@ -0,0 +1,54 @@
+# Services
+
+Service packages manage system services (systemd on Linux, launchd on macOS) through metool's package structure.
+
+## Contents
+
+- [systemd.md](systemd.md) - Linux systemd service management (user services with `--user`)
+- [launchd.md](launchd.md) - macOS launchd service management (LaunchAgents)
+
+## Overview
+
+Service packages follow a standard pattern with unified commands for cross-platform service management:
+
+- `install` - Install and configure the service
+- `start` / `stop` / `restart` - Control service state
+- `status` - Show service status
+- `enable` / `disable` - Control autostart at boot/login
+- `logs` - View service logs
+- `config` - Manage service configuration
+
+## Quick Reference
+
+### Service Package Structure
+
+```
+service-name/
+├── bin/
+│   └── mt-service           # Main service management command
+├── libexec/
+│   └── service-name/        # Subcommands (start, stop, status, etc.)
+├── lib/
+│   └── service-functions.sh # Shared functions
+├── config/
+│   ├── dot-config/
+│   │   └── systemd/user/    # User systemd units
+│   └── macos/
+│       └── com.service.plist # launchd configuration
+└── shell/
+    └── aliases              # Service management aliases
+```
+
+### Common Commands
+
+```bash
+mt-service status            # Check if service is running
+mt-service start             # Start the service
+mt-service logs -f           # Follow service logs
+mt-service enable            # Start at boot/login
+```
+
+## See Also
+
+- [docs/templates/service-package/](../templates/service-package/) - Complete service package template
+- [docs/packages/README.md](../packages/README.md) - General package structure
diff --git a/docs/services/launchd.md b/docs/services/launchd.md
new file mode 100644
index 0000000..fbd07ea
--- /dev/null
+++ b/docs/services/launchd.md
@@ -0,0 +1,155 @@
+# macOS launchd Services
+
+Managing services on macOS with launchd.
+
+## Overview
+
+launchd is macOS's service management system, similar to systemd on Linux. Service packages can include launchd configuration for macOS support.
+
+## Plist Location
+
+User launch agents go in `~/Library/LaunchAgents/`:
+
+```
+package-name/
+└── config/
+    └── macos/
+        └── com.user.service-name.plist
+```
+
+During installation, the plist is symlinked or copied to `~/Library/LaunchAgents/`.
+
+## Plist Template
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.user.service-name</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/service-binary</string>
+        <string>--config</string>
+        <string>/Users/USERNAME/.config/service-name/config.yml</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>/tmp/service-name.out</string>
+
+    <key>StandardErrorPath</key>
+    <string>/tmp/service-name.err</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>SERVICE_HOME</key>
+        <string>/Users/USERNAME/.config/service-name</string>
+    </dict>
+</dict>
+</plist>
+```
+
+## Common Commands
+
+```bash
+# Load service (start)
+launchctl load ~/Library/LaunchAgents/com.user.service-name.plist
+
+# Unload service (stop)
+launchctl unload ~/Library/LaunchAgents/com.user.service-name.plist
+
+# Check if running
+launchctl list | grep service-name
+
+# View logs
+tail -f /tmp/service-name.out
+tail -f /tmp/service-name.err
+```
+
+## Shell Aliases
+
+Add to package's `shell/aliases`:
+
+```bash
+# Service management aliases
+alias service-logs='tail -f /tmp/service-name.out'
+alias service-status='launchctl list | grep service-name'
+alias service-start='launchctl load ~/Library/LaunchAgents/com.user.service-name.plist'
+alias service-stop='launchctl unload ~/Library/LaunchAgents/com.user.service-name.plist'
+```
+
+## Key Plist Options
+
+### RunAtLoad
+
+Start service when user logs in:
+
+```xml
+<key>RunAtLoad</key>
+<true/>
+```
+
+### KeepAlive
+
+Restart service if it exits:
+
+```xml
+<key>KeepAlive</key>
+<true/>
+```
+
+Or only restart on failure:
+
+```xml
+<key>KeepAlive</key>
+<dict>
+    <key>SuccessfulExit</key>
+    <false/>
+</dict>
+```
+
+### WorkingDirectory
+
+Set working directory:
+
+```xml
+<key>WorkingDirectory</key>
+<string>/path/to/directory</string>
+```
+
+### StartInterval
+
+Run periodically (in seconds):
+
+```xml
+<key>StartInterval</key>
+<integer>3600</integer>
+```
+
+## Debugging
+
+Check launchd logs:
+
+```bash
+# System log for launchd issues
+log show --predicate 'subsystem == "com.apple.xpc.launchd"' --last 5m
+
+# Check if plist is valid
+plutil -lint ~/Library/LaunchAgents/com.user.service-name.plist
+```
+
+## See Also
+
+- [systemd.md](systemd.md) - Linux service management
+- [../templates/service-package/README.md](../templates/service-package/README.md) - Service package template
diff --git a/docs/systemd.md b/docs/services/systemd.md
similarity index 100%
rename from docs/systemd.md
rename to docs/services/systemd.md
diff --git a/docs/skills/README.md b/docs/skills/README.md
new file mode 100644
index 0000000..1a95bd0
--- /dev/null
+++ b/docs/skills/README.md
@@ -0,0 +1,68 @@
+# Skills
+
+Skills extend Claude Code's capabilities by providing specialized knowledge, workflows, and tools. Metool packages can include a `SKILL.md` file to enable AI assistance for the package's domain.
+
+## Contents
+
+- [creating.md](creating.md) - How to create a SKILL.md file
+- [structure.md](structure.md) - SKILL.md format and frontmatter requirements
+- [progressive-disclosure.md](progressive-disclosure.md) - Token-efficient skill design patterns
+
+## What Skills Provide
+
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with specific file formats or APIs
+3. **Domain expertise** - Package-specific knowledge, schemas, conventions
+4. **Bundled resources** - Scripts, docs, and assets accessible to Claude
+
+## Human-AI Collaborative Infrastructure
+
+Metool packages with skills create infrastructure that serves both humans and AI:
+
+**For Humans:**
+- Scripts in `bin/` provide CLI tools available in PATH
+- Shell functions and aliases in `shell/` enhance interactive workflows
+- Configuration in `config/` manages dotfiles and settings
+- `README.md` documents the package for human users
+
+**For AI (Claude):**
+- `SKILL.md` provides procedural knowledge and workflow guidance
+- References to `bin/` scripts tell Claude what tools are available
+- Documentation in `docs/` enables progressive disclosure
+- Understanding of `shell/` functions helps Claude guide interactive usage
+
+## Quick Reference
+
+### Adding a Skill to a Package
+
+1. Create `SKILL.md` in the package root
+2. Add required frontmatter (name, description)
+3. Run `mt package install` to register the skill
+
+### SKILL.md Template
+
+```markdown
+---
+name: package-name
+description: Brief explanation. This skill should be used when [scenarios].
+---
+
+# Package Name
+
+## Overview
+[What this skill enables]
+
+## Workflows
+[Step-by-step procedures with tool references]
+```
+
+### Skill Installation
+
+When installed via `mt package install`, metool creates symlinks:
+1. Package → `~/.metool/skills/<package-name>`
+2. `~/.metool/skills/<package-name>` → `~/.claude/skills/<package-name>`
+
+## See Also
+
+- [docs/packages/README.md](../packages/README.md) - Package structure
+- [docs/packages/structure.md](../packages/structure.md) - SKILL.md in package context
diff --git a/docs/skills/creating.md b/docs/skills/creating.md
new file mode 100644
index 0000000..ce5604f
--- /dev/null
+++ b/docs/skills/creating.md
@@ -0,0 +1,103 @@
+# Creating Skills
+
+How to add Claude Code skill support to a metool package.
+
+## Overview
+
+Skills extend Claude Code's capabilities by providing specialized knowledge for a package's domain. When you add a `SKILL.md` file to a package, Claude can load it to understand the package's tools and workflows.
+
+## Quick Start
+
+### Option 1: New Package with Skill
+
+```bash
+mt package new my-package /path/to/module
+```
+
+This creates a package with `SKILL.md.example`. Rename to `SKILL.md` to activate.
+
+### Option 2: Add Skill to Existing Package
+
+Create `SKILL.md` in the package root:
+
+```markdown
+---
+name: package-name
+description: Brief explanation. This skill should be used when [scenarios].
+---
+
+# Package Name
+
+## Overview
+
+[What this package enables]
+
+## Available Tools
+
+- `tool-name` - Description of what the tool does
+
+## Workflows
+
+[Step-by-step procedures]
+```
+
+## Installation
+
+When installed via `mt package install`, metool automatically creates symlinks:
+
+1. Package → `~/.metool/skills/<package-name>`
+2. `~/.metool/skills/<package-name>` → `~/.claude/skills/<package-name>`
+
+Claude Code discovers skills by scanning `~/.claude/skills/` for `SKILL.md` files.
+
+## Writing Effective Skills
+
+### Content Guidelines
+
+- Focus on **procedural knowledge** Claude cannot infer from code
+- Reference package tools by their command names (they're in PATH after install)
+- Point to `docs/` files for detailed reference material
+- Include concrete examples with realistic scenarios
+
+### Writing Style
+
+Use imperative/infinitive form:
+
+```markdown
+# Good
+To clean up branches, run `git-branch-clean`.
+
+# Avoid
+You should run git-branch-clean to clean up branches.
+```
+
+### Size Limits
+
+- Keep SKILL.md under **5k words**
+- Move detailed content to `docs/` and link to it
+- Use progressive disclosure (see [progressive-disclosure.md](progressive-disclosure.md))
+
+## Human-AI Collaborative Infrastructure
+
+Packages with skills serve both humans and AI:
+
+| For Humans | For AI (Claude) |
+|------------|-----------------|
+| Scripts in `bin/` - CLI tools | `SKILL.md` - Procedural knowledge |
+| Shell functions in `shell/` | Tool references in skill |
+| `README.md` - Documentation | `docs/` - Detailed reference |
+| `config/` - Settings | Understanding of workflows |
+
+## Validation
+
+Validate package structure and skill:
+
+```bash
+mt package validate package-name
+```
+
+## See Also
+
+- [structure.md](structure.md) - SKILL.md format requirements
+- [progressive-disclosure.md](progressive-disclosure.md) - Token-efficient design
+- [../packages/structure.md](../packages/structure.md) - Package structure
diff --git a/docs/skills/progressive-disclosure.md b/docs/skills/progressive-disclosure.md
new file mode 100644
index 0000000..5d22e38
--- /dev/null
+++ b/docs/skills/progressive-disclosure.md
@@ -0,0 +1,125 @@
+# Progressive Disclosure
+
+Token-efficient patterns for skill design.
+
+## The Problem
+
+Claude Code has limited context. Loading a large skill wastes tokens on content that may not be needed for the current task.
+
+## Three-Level Loading
+
+Skills use progressive disclosure with three levels:
+
+| Level | Content | When Loaded | Size Target |
+|-------|---------|-------------|-------------|
+| 1. Metadata | name + description | Always in context | ~100 words |
+| 2. SKILL.md | Quick reference | When skill triggers | <5k words |
+| 3. docs/ | Detailed content | On demand | Unlimited |
+
+### Level 1: Metadata
+
+Always visible in skill listings. Used to decide whether to load the skill.
+
+```yaml
+---
+name: git-tools
+description: Git workflow utilities. This skill should be used when cleaning up branches or managing worktrees.
+---
+```
+
+### Level 2: SKILL.md Body
+
+Loaded when the skill is triggered. Should be a navigation layer:
+
+- Brief overview of capabilities
+- Most common commands (Pareto principle: 20% used 80% of time)
+- Links to detailed docs
+
+### Level 3: docs/ Directory
+
+Loaded only when Claude needs specific details:
+
+```markdown
+For complete branch cleanup options, see [docs/branch-cleanup.md](docs/branch-cleanup.md).
+```
+
+## Design Principles
+
+### SKILL.md as Navigation Layer
+
+**Key insight:** SKILL.md should contain NO unique content. Everything should exist in docs/ or README.md.
+
+Benefits:
+- Humans maintain content in docs/ where they can review it
+- Skills stay small and focused
+- No duplication between SKILL.md and docs
+
+### Topic Block Pattern
+
+Each topic in SKILL.md follows this pattern:
+
+1. **What & Why** - One sentence
+2. **Link to docs** - Must be a file, not directory
+3. **Common command** (optional) - Only most-used
+
+Example:
+```markdown
+### Branch Cleanup
+
+Remove merged branches to keep repository clean.
+
+See [docs/packages/branch-cleanup.md](docs/packages/branch-cleanup.md) for options.
+
+\`\`\`bash
+git-branch-clean    # Remove merged branches
+\`\`\`
+```
+
+### Pareto Principle for Commands
+
+Only include commands used 80% of the time. Detailed command reference goes in docs/.
+
+```markdown
+## Essential Commands
+
+\`\`\`bash
+git-branch-clean     # Most common
+git-worktree-list    # Frequently used
+\`\`\`
+
+For all commands, see [docs/commands/README.md](docs/commands/README.md).
+```
+
+## Link Requirements
+
+Links must always target a specific markdown file, not a directory:
+
+```markdown
+# Good
+See [docs/skills/README.md](docs/skills/README.md)
+
+# Bad
+See [docs/skills/](docs/skills/)
+```
+
+## Size Guidelines
+
+| Component | Target Size |
+|-----------|-------------|
+| Frontmatter description | <200 characters |
+| SKILL.md total | <5k words |
+| Individual docs | As needed |
+
+## Refactoring Large Skills
+
+If SKILL.md exceeds 5k words:
+
+1. Identify sections that are reference material
+2. Move to appropriate docs/ location
+3. Replace with brief summary + link
+4. Keep only navigation and common commands in SKILL.md
+
+## See Also
+
+- [creating.md](creating.md) - Creating skills
+- [structure.md](structure.md) - SKILL.md format
diff --git a/docs/skills/structure.md b/docs/skills/structure.md
new file mode 100644
index 0000000..8c71569
--- /dev/null
+++ b/docs/skills/structure.md
@@ -0,0 +1,160 @@
+# SKILL.md Structure
+
+Format and requirements for SKILL.md files.
+
+## File Location
+
+```
+package-name/
+├── README.md     # Human documentation
+├── SKILL.md      # AI skill (Claude Code)
+└── ...
+```
+
+## Required Frontmatter
+
+Every SKILL.md must start with YAML frontmatter:
+
+```yaml
+---
+name: package-name
+description: Brief explanation. This skill should be used when [scenarios].
+---
+```
+
+### name
+
+- Must be **hyphen-case** (lowercase letters, digits, hyphens only)
+- Should match the package name
+- Examples: `git-tools`, `docker-helpers`, `my-package`
+
+### description
+
+- Clear explanation of when Claude should use this skill
+- Use **third-person** ("This skill should be used when...")
+- Include specific trigger scenarios
+- Keep under 200 characters for the skill list
+
+Example:
+```yaml
+description: Git workflow utilities. This skill should be used when cleaning up branches, managing worktrees, or automating git operations.
+```
+
+## Recommended Sections
+
+```markdown
+---
+name: package-name
+description: ...
+---
+
+# Package Name
+
+## Overview
+
+[1-2 sentences about what this enables]
+
+## When to Use
+
+[Specific triggers and use cases - bulleted list]
+
+## Available Tools
+
+[List of commands with brief descriptions]
+
+## Workflows
+
+[Step-by-step procedures for common tasks]
+
+## See Also
+
+[Links to related docs and packages]
+```
+
+## Section Guidelines
+
+### Overview
+
+Brief, focused description:
+
+```markdown
+## Overview
+
+Git branch management tools for cleaning merged branches and maintaining worktrees.
+```
+
+### When to Use
+
+Specific scenarios that trigger skill loading:
+
+```markdown
+## When to Use
+
+- Cleaning up merged or stale branches
+- Managing git worktrees
+- Automating branch operations
+```
+
+### Available Tools
+
+Command reference with descriptions:
+
+```markdown
+## Available Tools
+
+- `git-branch-clean` - Remove merged local branches
+- `git-worktree-list` - List all worktrees with status
+```
+
+### Workflows
+
+Step-by-step procedures:
+
+```markdown
+## Workflows
+
+### Cleaning Up After Feature Merge
+
+1. Ensure feature is merged: `git log main --oneline | head -5`
+2. Run cleanup: `git-branch-clean`
+3. Verify: `git branch`
+```
+
+## Anti-Patterns
+
+### Avoid Duplicating README
+
+```markdown
+# Bad - duplicates README content
+## Installation
+\`\`\`bash
+mt package install git-tools
+\`\`\`
+```
+
+Installation belongs in README.md, not SKILL.md.
+
+### Avoid Second Person
+
+```markdown
+# Bad
+You should run git-branch-clean to clean branches.
+
+# Good
+To clean branches, run `git-branch-clean`.
+```
+
+### Avoid Excessive Detail
+
+```markdown
+# Bad - too detailed for SKILL.md
+Here is a 500-line explanation of git internals...
+
+# Good
+For git internals, see [docs/git-internals.md](docs/git-internals.md).
+```
+
+## See Also
+
+- [creating.md](creating.md) - How to create skills
+- [progressive-disclosure.md](progressive-disclosure.md) - Size management