How to use the Setup TS Deep Modules agent skill

What the skill makes the agent do

The skill turns each package in a TypeScript repo into a deep module: a lot of behaviour behind a small public interface. A package's public surface is its entry points, meaning the files at the package root. Everything in its subfolders is treated as hidden implementation.

The skill adds four rules, all set to error. Code outside a package may import only its entry points. A package's own files may import each other freely. Test files may import entry points and their own fixtures, but not any package's subfolder internals. And dependency cycles are not allowed.

The agent also adds a lint:boundaries script, folds it into your existing umbrella check that runs typecheck, creates a starter example package, and writes a README in the packages folder that explains the convention. Finally it adds a pointer to that README in CLAUDE.md or AGENTS.md so future agents find the rule.

Install the skill (ZIP or Claude app upload)

Download the ZIP of the skill from this page. Then choose one of two routes. For Claude Code, unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder to limit it to that repo. In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.

The listed files are agents/openai.yaml and SKILL.md. SKILL.md links to a config file named dependency-cruiser.config.cjs, which is not in the file list on this page, so confirm it is inside the unzipped folder before you run the skill.

• Claude Code, all projects: unzip into ~/.claude/skills/
• Claude Code, one project: unzip into the project's .claude/skills/
• Claude apps: upload under Settings, then Capabilities, then Skills

Trigger the skill with a clear request

This skill is user-invoked. The skill's metadata turns off automatic model invocation, so the agent is not expected to pick it up from a loose hint. Name it directly in your request so the agent knows to load it.

Good requests state the goal and the skill. For example, you can ask the agent to use the setup-ts-deep-modules skill on this repo so that packages only import through their entry points. Before the agent starts, it will check the environment: which package manager the repo uses, where the packages folder is, and whether a dependency-cruiser config already exists.

• Use the setup-ts-deep-modules skill to set up deep-module boundaries in this repo.
• Use setup-ts-deep-modules to add lint:boundaries next to typecheck.
• Apply the setup-ts-deep-modules skill and show me which existing config lines you changed.

What the agent does and how you verify it

The agent first detects your environment. It reads the lockfile to pick pnpm, yarn, bun or npm, and it uses a src/packages folder if src/ exists, otherwise packages. It installs dependency-cruiser as a devDependency and copies the config to the repo root as .dependency-cruiser.cjs, setting the packages root.

The skill's completion test is a proof step. The agent runs lint:boundaries and expects a pass on the clean example. It then adds a deliberate deep import such as import { thing } from "../lib/impl" to tests/example.test.ts, expects a failure under the rule tests-through-entrypoints, and reverts the change to see a pass again. If the deliberate violation does not fail, the skill says the rules are not wired correctly and must be fixed before finishing.

You can repeat this check yourself. Run the boundary check after the agent finishes, and confirm that the deep import is gone from the example test.

• Pass on the clean example
• Fail on the deliberate deep import, under tests-through-entrypoints
• Pass again after the deep import is reverted

Example: what the resulting layout looks like

The skill enforces a layout where each package has root entry points, an implementation folder called lib/, and a tests/ folder. The rule itself covers any subfolder, so you never need to edit the config to add one. Packages are flat: one level of packages directly under the root, and a package may not contain another package.

Barrel files that re-export a whole subtree are discouraged. Instead, a package can expose several small entry points, such as index.ts, client.ts and server.ts.

• src/packages/<name>/index.ts is a public entry point
• src/packages/<name>/client.ts can be another entry point
• src/packages/<name>/lib/ holds hidden implementation
• src/packages/<name>/tests/ holds co-located tests and fixtures

Tips and safety notes before you run it

The skill is intrusive by design. Its own description says it may overwrite or conflict with an existing setup, though it asks to merge when a .dependency-cruiser config already exists. Read the diff before you accept it, and take a commit first so you can revert.

The skill runs scripts and uses the network, because installing dependency-cruiser requires your package manager. Review the commands the agent proposes before approving them. The skill also says it does not touch tsconfig or add path aliases, so check that those files are unchanged afterward.

Do not flatten the config's $1 back-references into separate per-package rules. The skill notes that these back-references are what let a package reach its own internals while outsiders cannot.

• Commit your work before running the skill.
• Check the diff of any existing .dependency-cruiser config.
• Expect the agent to add a lint:boundaries script and a README in the packages folder.
• Layering rules between packages are a commented stub for you to fill in.