tach
Skill126 starsChanged 9 months agoApache-2.0View on GitHub
This skill should be used when the user asks to "add a tach module", "configure tach layers", "define module boundaries", "set up interfaces", "run tach check", "check module boundaries", "tach sync", "tach show", "deprecate a dependency", "tach-ignore", "unchecked modules", "tach test", "skip tests with tach", "configure tach.toml", "source roots", "forbid circular dependencies", "enforce module boundaries", "set up architectural layers", or "tach init".
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- claude-improve-configSkill
- docs-page-frontmatterSkill
- hypothesisSkill
- narwhalsSkill
- sybilSkill
- syrupySkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 0 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Run uv run tach check to verify boundaries.
- Very specific: line 18
Run uv run pytest --tach to skip tests unaffected by changes (uses tach's module dependency graph for impact analysis).
- Very specific: line 107
Add the module definition to tach.toml with path, layer, and depends_on
- Very specific: line 108
Run tach sync --add to discover any additional dependencies
- Very specific: line 109
Run tach check to verify
- Very specific: line 113
Update the layer field in tach.toml
- Very specific: line 115
Run tach check to verify no violations
- Very specific: line 122
Add the dependency to depends_on in tach.toml
- Very specific: line 124
Use # tach-ignore for exceptions
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Tach
Tach enforces module boundaries in Python codebases. It verifies that imports between modules respect declared dependencies and public interfaces, with no runtime impact.
For full documentation: https://docs.gauge.sh/
How This Project Uses Tach
The project defines three architectural layers in tach.toml: cli > ext > core. Higher layers may import from lower layers without declaring dependencies. Same-layer imports require explicit depends_on declarations. Unlayered facade and primitive modules (e.g., metaxy, metaxy._decorators) sit outside the layer hierarchy.
Run uv run tach check to verify boundaries. The pre-commit hook runs this automatically on src/ changes.
Run uv run pytest --tach to skip tests unaffected by changes (uses tach's module dependency graph for impact analysis).
Core Commands
| Command | Purpose |
tach init | Guided setup: walks through tach mod, tach sync, tach show |
tach mod | Interactive terminal UI to mark module boundaries |
tach sync | Sync tach.toml with actual imports (--add to only add) |
tach check | Report boundary/interface violations (--exact for unused deps) |
tach check-external | Validate 3rd-party imports match pyproject.toml |
tach show | Visualize dependency graph (--web, --mermaid, -o) |
tach map | JSON dependency map between files (--closure for transitives) |
tach report | Dependencies/usages of a module (--dependencies, --usages) |
tach test | Run only tests impacted by changes |
tach install | Install as pre-commit hook |
Full command reference: https://docs.gauge.sh/usage/commands/
Key Concepts
Modules
A module is a Python package or file with dependencies configured in tach.toml. Identified by import path from the nearest source root (e.g., metaxy.config for src/metaxy/config/).
[[modules]]
path = "metaxy.config"
layer = "core"
depends_on = ["metaxy._decorators", "metaxy.models"]Special attributes:
utility: true— accessible to all modules without declaring dependencyunchecked: true— no dependency restrictions (for incremental adoption)visibility: []— isolate module from external importscannot_depend_on— forbidden dependencies (takes precedence overdepends_on)
Layers
Ordered architectural tiers. Higher layers may freely import from lower layers; lower layers may never import from higher layers. Same-layer imports require explicit depends_on.
layers = ["cli", "ext", "core"]Set layers_explicit_depends_on = true to require all cross-layer dependencies be declared explicitly. Mark a layer as closed with { name = "commands", closed = true } to force higher layers through the intermediary.
Full layers documentation: https://docs.gauge.sh/usage/layers/
Interfaces
Define public APIs to prevent deep coupling. Only imports matching expose patterns are allowed.
[[interfaces]]
expose = ["get_data"]
from = ["core"]Interfaces support visibility to restrict consumers and exclusive: true to override other interfaces.
Full interfaces documentation: https://docs.gauge.sh/usage/interfaces/
Deprecation
Mark dependencies as deprecated to surface usage without failing checks:
depends_on = [{ path = "core", deprecated = true }]tach-ignore
Suppress specific violations with inline comments:
# tach-ignore
from core.main import private_function
from core.api import priv, pub # tach-ignore privAdd reasons: # tach-ignore(reason here) member_name
Common Tasks
Add a New Module
- Add the module definition to
tach.tomlwithpath,layer, anddepends_on - Run
tach sync --addto discover any additional dependencies - Run
tach checkto verify
Move a Module Between Layers
- Update the
layerfield intach.toml - Adjust
depends_onbased on new layer relationships - Run
tach checkto verify no violations
Debug Boundary Violations
Error format: file.py[L8]: Cannot import 'foo.bar'. Module 'baz' cannot depend on 'foo'.
Options:
- Add the dependency to
depends_onintach.toml - Mark dependency as
deprecatedto track without blocking - Use
# tach-ignorefor exceptions - Restructure imports to go through public interfaces
Configuration Reference
Full configuration documentation: https://docs.gauge.sh/usage/configuration/
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

