# Tool Skills

Modern developer tools move fast. LLMs are notoriously prone to hallucinating outdated command flags, inventing non-existent configuration options, or invoking commands outside the hermetic project environment.

The **`tool-*`** skill suite provides **deterministic execution groundings**. It gives AI assistants verified CLI syntax, configuration schemas, and step-by-step runbooks for every compiler, linter, test runner, and utility in the Zenith stack.

Rather than letting models guess how a tool works, Zenith equips them with verified, version-pinned knowledge.

## Package Management & Task Execution

These tools manage dependencies, repeatable project tasks, and command-line workflows.

### Fast Packaging & Environment Isolation (tool-uv)

**What it is**: The skill governing Astral's high-speed package installer and resolver.

**Why it's in Zenith**: Python dependency management historically suffered from sluggish resolvers, broken environment isolation, and fragmentation between tools. `uv` replaces this ecosystem with a single Rust binary that resolves packages in milliseconds and guarantees reproducible environments via `uv.lock`.

The `tool-uv` skill grounds agents in hermetic execution: running commands via `uv run`, managing dependency groups (`dev`, `docs`), and performing cross-platform lockfile updates.

### Hermetic Task Automation (tool-poethepoet)

**What it is**: The runbook for Zenith's declarative task runner, Poe the Poet.

**Why it's in Zenith**: Development teams often rely on ad-hoc shell scripts or obscure `Makefile` targets that fail across operating systems. Poe the Poet defines development tasks directly inside `poe_tasks.toml` and runs them strictly within the isolated `uv` virtual environment.

`tool-poethepoet` teaches agents standard repository tasks—such as `uv run poe test`, `uv run poe code-quality`, and `uv run poe fix`—as well as argument forwarding and task composition patterns.

### Rust-Native Git Pre-Commit Hooks (tool-prek)

**What it is**: The skill for running and configuring Git pre-commit lifecycle hooks using `prek`.

**Why it's in Zenith**: Traditional Python `pre-commit` incurs noticeable startup latency and requires isolated environments for every hook. `prek` is a fast, Rust-native drop-in alternative that executes configured checks in parallel with minimal overhead.

`tool-prek` guides agents through hook installations (`uv run prek install`), manual workspace audits (`uv run prek run --all-files`), and `prek.toml` configuration syntax.

### Modern Type-Safe CLI Development (tool-typer)

**What it is**: The design guide and syntax reference for building modern command-line interfaces using Typer and Rich.

**Why it's in Zenith**: Building CLIs with Python's standard `argparse` requires verbose boilerplate. Typer leverages modern Python type hints and PEP 593 `Annotated` metadata to auto-generate help text, validate arguments, and format output with Rich terminal components.

`tool-typer` ensures agents build CLIs adhering to Zenith typing standards, using lazy subcommand imports for fast startup and providing clean terminal panes.

### Template Instantiation & Scaffolding (tool-cookiecutter)

**What it is**: The skill for maintaining and testing Zenith's Cookiecutter template engine, variables, and lifecycle hooks.

**Why it's in Zenith**: Zenith is itself a Cookiecutter template. Maintaining `cookiecutter.json`, conditional file trees, and Jinja templating hooks requires strict attention to variable scoping and post-generation scripts.

`tool-cookiecutter` provides maintainers and agents with syntax rules for conditional blocks, prompt definitions (`__prompts__`), and multi-platform rendering tests.

## Code Quality, Static Typing & Architecture

These tools check source style, type correctness, module boundaries, and complexity.

### Unified Linting & Formatting (tool-ruff)

**What it is**: The operational guide for Astral Ruff, the unified Python linter and code formatter.

**Why it's in Zenith**: Historically, Python projects combined multiple separate formatters and linters, resulting in slow CI builds and conflicting formatting rules. Ruff replaces dozens of tools with a single Rust engine operating 10–100x faster than legacy alternatives.

`tool-ruff` guides agents through Zenith's complete rule configuration (including preview rules and type-checking imports), safe auto-fixing (`ruff check --fix`), and formatting rules.

### Strict Static Type Checking (tool-pyrefly)

**What it is**: The reference guide for Meta's high-speed Pyrefly static type checker.

**Why it's in Zenith**: Static typing is the bedrock of agentic reliability. When types are loose or unverified, AI assistants frequently introduce runtime `TypeError` or `AttributeError` exceptions. Pyrefly provides near-instantaneous feedback, first-class support for modern PEP 695 generic syntax, and strict structural subtyping.

`tool-pyrefly` teaches agents how to interpret Pyrefly diagnostics, write compliant type aliases, and enforce 100% strict type coverage across domain packages.

### Modular Architecture & Boundary Enforcement (tool-tach)

**What it is**: The skill for defining and enforcing module layer boundaries with Tach.

**Why it's in Zenith**: As codebases expand, modular boundaries erode into circular dependencies and improper layer coupling. Tach enforces explicit import rules directly in the AST.

`tool-tach` ensures agents respect defined layer hierarchies, update `tach.toml` when adding new modules, and resolve circular dependencies using dependency injection or protocols.

### Cognitive Complexity Ceiling (tool-complexipy)

**What it is**: The runbook for measuring cognitive complexity and refactoring dense code.

**Why it's in Zenith**: While cyclomatic complexity measures linear code branches, cognitive complexity measures how difficult code is for a human mind or an LLM to comprehend. Deeply nested loops and defensive branch conditions are magnets for bugs.

Zenith sets a strict ceiling: **no function may exceed a cognitive complexity score of 10**. `tool-complexipy` provides agents with concrete refactoring recipes (guard clauses, functional extraction, lookup tables) to reduce complexity scores.

### Public API Change Detection (tool-griffe)

**What it is**: The skill for static AST inspection of Python public API signatures using Griffe.

**Why it's in Zenith**: Unintended breaking changes in public APIs break downstream consumers. Griffe parses public docstrings and AST signatures without importing or executing untrusted code.

In Zenith, `tool-griffe` powers automated API diff audits during Spec-Driven Development reviews (`uv run poe sdd-check-api`), ensuring every new, modified, or removed symbol is intentional.

### Source Code & Documentation Spelling Verification (tool-typos)

**What it is**: The guide for source code and documentation spell checking via `typos`.

**Why it's in Zenith**: Typos in code identifiers, configuration keys, or documentation anchor links degrade project polish and cause subtle runtime bugs. `typos` is a zero-dependency Rust tool that scans codebases in milliseconds with virtually zero false positives.

`tool-typos` guides agents on running spell checks, maintaining `typos.toml` exclusion lists for acronyms, and fixing documentation prose.

## Testing, Coverage & Security Assurance

These tools check behavior, coverage, dependency safety, and CI workflows.

### Test Suite Execution (tool-pytest)

**What it is**: The runbook for Zenith's pytest test suite and ecosystem plugins.

**Why it's in Zenith**: High-assurance engineering requires more than simple unit tests. Zenith's test stack integrates `pytest-xdist` for multi-core parallel execution, `pytest-randomly` for order-independent test isolation, `syrupy` for snapshot testing, and `hypothesis` for property-based fuzz testing.

`tool-pytest` grounds agents in writing assertive tests, using fixtures, debugging test failures, and managing test execution parameters.

### 100% Branch Coverage Enforcement (tool-coverage)

**What it is**: The configuration and enforcement guide for Coverage.py.

**Why it's in Zenith**: Statement coverage is deceptive: a test can execute a line without testing both branches of an `if` condition. Zenith enforces **100% branch and statement coverage** (`fail_under = 100`) as a mandatory quality gate.

`tool-coverage` helps agents inspect missed branches (`coverage report -m`), understand `.coveragerc` exclusion patterns, and write targeted test scenarios to kill uncovered branches.

### Local AST Mutation Testing (tool-mutmut)

**What it is**: The guide for high-speed AST mutation testing with `mutmut`.

**Why it's in Zenith**: 100% test coverage proves that code was executed, but not that the tests actually assert anything meaningful. Mutation testing modifies your AST (for example, flipping boolean operators) to verify whether tests fail.

`tool-mutmut` provides a fast, interactive mutation loop for local development, helping developers and agents discover surviving mutants and write deeper test assertions.

### Cross-Platform Mutation Testing (tool-cosmic-ray)

**What it is**: The skill for thorough, cross-platform mutation testing with Cosmic Ray.

**Why it's in Zenith**: While `mutmut` excels at fast local developer loops, Cosmic Ray provides comprehensive AST mutation sweeps across all supported platforms, including Windows environments.

`tool-cosmic-ray` teaches agents how to initialize SQLite mutation databases, execute distributed mutation workers, and analyze survivor summaries.

### GitHub Actions CI/CD Security Audit (tool-zizmor)

**What it is**: The static security analyzer for GitHub Actions workflows.

**Why it's in Zenith**: CI/CD workflows are frequent targets for supply-chain attacks, script injections, unpinned third-party actions, and excessive token permissions.

`tool-zizmor` audits all `.github/workflows/*.yaml` files in pedantic mode, ensuring workflows follow least-privilege permissions, pin actions to full commit SHAs, and guard against arbitrary script execution.

## Documentation, Assets & Formatting

These tools build documentation and keep its source files and visual assets consistent.

### Modern TOML-Based Documentation (tool-zensical)

**What it is**: The operational guide for Zensical, Zenith's modern static documentation generator.

**Why it's in Zenith**: Traditional documentation generators often rely on slow builds, complex Python configurations, or legacy themes. Zensical is configured entirely via TOML (`zensical.toml`) and features instant live-reloading, automatic `llms.txt` generation, Lucide icons, and native dark/light mode switching.

`tool-zensical` guides agents in serving documentation locally (`uv run poe docs-serve`), organizing navigation hierarchies, and configuring `mkdocstrings` for automatic API docs.

### Rust-Native Markdown Linter & Formatter (tool-rumdl)

**What it is**: The skill for formatting and linting documentation with `rumdl`.

**Why it's in Zenith**: Markdown documentation easily drifts into inconsistent heading styles, broken links, and irregular list formatting. `rumdl` formats markdown at Rust speeds and features integrated code-block tools that format embedded Python blocks with Ruff.

`tool-rumdl` guides agents in validating markdown documentation (`uv run poe lint-md`), formatting prose, and resolving rule diagnostics.

### Declarative TOML Formatting & Linting (tool-taplo)

**What it is**: The formatting and schema validation guide for TOML configuration files.

**Why it's in Zenith**: Zenith organizes configurations into dedicated TOML files (`pyproject.toml`, `tach.toml`, `zensical.toml`, `poe_tasks.toml`). Without automated formatting, key-value pairs become disorganized and hard to read.

`tool-taplo` enforces aligned keys, 4-space indentation, and valid schemas across all TOML manifests via `uv run poe format-check-toml`.

### Consistent YAML & CSS Formatting (tool-prettier)

**What it is**: The formatting guide for GitHub Actions YAML manifests and custom CSS stylesheets using Prettier.

**Why it's in Zenith**: While Ruff and Taplo format Python and TOML, GitHub Actions workflows and Zensical CSS styling require consistent multi-line indentation and quote normalization.

`tool-prettier` formats all YAML and CSS files automatically to prevent noisy Git diffs.

### Vector Logotypes & Asset Generation (tool-typst)

**What it is**: The guide for authoring vector SVG logotypes and diagrams using the Typst typesetting engine.

**Why it's in Zenith**: Raster images (PNG, JPEG) blur on high-DPI displays and cannot be edited in code. Typst compiles human-readable code into crisp, responsive vector SVG assets (such as `docs/assets/python-logo.svg`).

`tool-typst` grounds agents in Typst layout markup, mathematical positioning, and SVG export workflows.

### Animated Terminal Documentation Widgets (tool-termynal)

**What it is**: The skill for authoring interactive terminal animations in documentation.

**Why it's in Zenith**: Static CLI output in documentation is dry and unengaging. Termynal provides lightweight animated terminal widgets that simulate real CLI sessions with interactive controls and custom progress delays.

`tool-termynal` teaches agents how to wrap shell sessions in `<div class="termy">` tags with appropriate `data-ty` timing attributes.

## Adding Custom Tool Skills

When your project introduces major third-party libraries, databases, or cloud tools (such as Docker, FastAPI, Alembic, or Playwright), create a matching `tool-*` skill:

```bash
mkdir -p .agents/skills/tool-docker/{templates,references}
```

Equipping your agents with dedicated tool skills prevents hallucinated flags, guarantees idiomatic usage, and keeps your entire team operating on verified tool patterns.