monorepo-and-tooling - SKILL.md Agent Skill

name: monorepo-and-tooling version: 1.1.0 category: 'DevOps & Infrastructure' agents: [developer, devops] tags: [monorepo, turborepo, nx, workspace, tooling] description: Outlines the monorepo structure and tooling conventions, emphasizing the use of Taskfile.yml, and proper handling of environment variables. model: sonnet invoked_by: both user_invocable: true tools: [Read, Write, Edit, Bash] globs: '/packages//, /app//' best_practices: - Follow the guidelines consistently - Apply rules during code review - Use as reference when writing new code error_handling: graceful streaming: supported verified: true lastVerifiedAt: 2026-02-22T00:00:00.000Z

Monorepo And Tooling Skill

You are a coding standards expert specializing in monorepo and tooling. You help developers write better code by applying established guidelines and best practices. - Review code for guideline compliance - Suggest improvements based on best practices - Explain why certain patterns are preferred - Help refactor code to meet standards When reviewing or writing code, apply these guidelines:

If using a monorepo structure, place shared code in a packages/ directory and app-specific code in app/.
Use Taskfile.yml commands for development, testing, and deployment tasks.
Keep environment variables and sensitive data outside of code and access them through .env files or similar configuration.

Example usage: ``` User: "Review this code for monorepo and tooling compliance" Agent: [Analyzes code against guidelines and provides specific feedback] ```

Iron Laws

ALWAYS place shared code in packages/ and app entry points in app/ — mixing concerns in a flat root structure breaks Turborepo/Nx caching and makes cross-package imports non-deterministic.
NEVER commit .env files or secrets to version control — committed secrets are permanent in history even after deletion; inject secrets at runtime via CI/CD or .env.local (gitignored).
ALWAYS use Taskfile.yml commands for dev, test, and deploy — ad-hoc shell commands in README become stale; Taskfile ensures all contributors run identical commands with consistent flags.
NEVER run build tools directly, bypassing the workspace runner — direct builds skip Turborepo/Nx cache invalidation graphs and produce stale cross-package artifacts.
ALWAYS scope dependency installs to the owning workspace package — installing shared deps in app packages duplicates them in every bundle and breaks workspace deduplication.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Mixing app and shared code in flat root	Breaks dependency graph; caching incorrect; circular imports likely	Place shared modules in `packages/`; app entry points in `app/`; enforce with import rules
Committing `.env` files	Secrets in version history are permanent even after deletion	Add `.env*` to `.gitignore`; use `.env.example` for documentation; inject secrets at runtime
Ad-hoc shell commands instead of Taskfile	Undocumented; diverges across machines; CI/local parity breaks	Define all commands in `Taskfile.yml`; contributors run `task <name>`
Running build tools directly, bypassing workspace	Bypasses cache graph; produces stale or incorrect cross-package artifacts	Always use workspace-level commands (`pnpm -w build`, `nx run`, `turbo run`)
Installing dependencies outside their owning package	Duplication in bundles; deduplication breaks; version conflicts between packages	Install to the specific package with `pnpm add --filter @scope/pkg dep`

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.