metool

Package management for modular code organization. This skill should be used when creating, installing, or modifying metool packages, working with package structure conventions, or adding Claude Code skills to packages.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

Metool is a comprehensive package management skill designed for modular code organization and streamlined developer workflows. It enables the creation, installation, and modification of self-contained packages—including scripts, shell functions, and configurations—using GNU Stow for efficient symlink management. By providing a standardized structure and AI-ready documentation (SKILL.md), it bridges the gap between manual coding and AI-assisted development, making it an essential tool for maintaining clean, reusable, and AI-compatible codebases.

Use Cases

  • Modular Code Organization: Creating and managing self-contained units of code that include binaries, shell functions, and library scripts for better maintainability.
  • Dotfile and Configuration Management: Using the 'config/' directory structure to manage system dotfiles and deploy them via GNU Stow symlinks.
  • AI Skill Integration: Adding SKILL.md files to packages to provide Claude Code with the necessary context and instructions to interact with specific codebase functionalities.
  • System Service Deployment: Utilizing specialized templates to create and manage systemd or launchd services as modular packages.
  • Workflow Automation: Streamlining the promotion of code packages from development to public modules with built-in commands for diffing and moving components.
namemetool
descriptionPackage management for modular code organization. This skill should be used when creating, installing, or modifying metool packages, working with package structure conventions, or adding Claude Code skills to packages.

Metool Package Management

Overview

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.

See README.md for installation and getting started.

Quick Reference

Package Structure

package-name/
├── README.md        # Required
├── 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)

See docs/packages/structure.md for conventions.

Essential Commands

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 shell configuration

See docs/commands/README.md for full reference.

Workflows

Creating a Package

Create directory structure, add README.md, implement components, install.

See docs/packages/creation.md for step-by-step guide.

mt package new my-package /path/to/module  # Create from template

Adding a Skill to a Package

Create SKILL.md in package root with required frontmatter.

See docs/skills/README.md for skill creation.

Service Packages

For systemd/launchd services, use the service package template.

See docs/services/README.md for service management.

Package Promotion

Move packages between modules (dev → public).

See docs/packages/promotion.md for workflow.

mt package diff package-name dev pub  # Compare versions

Discovering Packages

mt module list                    # List modules in working set
mt package list                   # List all packages
mt package list | grep -w git     # Find specific package

Troubleshooting

Installation Conflicts

When config files conflict, remove existing files when prompted.

Prerequisites

mt deps              # Check dependencies
mt deps --install    # Auto-install on macOS

Requires: GNU coreutils, GNU Stow 2.4.0+

Documentation