coding-guidelines-gen
Generate nested AGENTS.md coding guidelines per module (monorepo-aware), detect languages/tooling, ask architecture preferences, and set up missing formatters/linters (Spotless for JVM). Use when the user wants module-scoped AGENTS.md coding guidelines or to set up missing formatters/linters.
When & Why to Use This Skill
This Claude skill automates the creation of module-specific coding guidelines and architectural boundaries within complex repositories or monorepos. It intelligently detects project languages, configures essential linting and formatting tools (such as Spotless for JVM), and generates verifiable 'AGENTS.md' files. By defining clear architecture styles and runnable command blocks, it ensures long-term code consistency and structural integrity.
Use Cases
- Monorepo Standardization: Automatically establish and maintain consistent coding standards across multiple sub-modules, ensuring that every part of a large project follows the same linting and formatting rules.
- Architectural Boundary Enforcement: Define and document strict dependency rules (e.g., preventing Domain layers from importing Infrastructure) to maintain Clean or Hexagonal architecture patterns.
- Automated Developer Environment Setup: Quickly bootstrap new or existing modules with pre-configured formatters and test commands, reducing the manual overhead of setting up development environments.
- AI-Ready Documentation: Generate verifiable command blocks that allow AI agents to autonomously run linting, formatting, and testing tasks to validate code quality before submission.
| name | coding-guidelines-gen |
|---|---|
| description | Generate nested AGENTS.md coding guidelines per module (monorepo-aware), detect languages/tooling, ask architecture preferences, and set up missing formatters/linters (Spotless for JVM). Use when the user wants module-scoped AGENTS.md coding guidelines or to set up missing formatters/linters. |
Coding guidelines generator
Goal
Create nested AGENTS.md files (not repo root) that define:
- architecture preferences + boundaries (high level)
- formatting/lint/testing commands (runnable)
- a small verifiable config block the verifier skill can execute
Minimal questions to ask (don’t skip)
- Where are the module roots? (Confirm the folders that should each get an
AGENTS.md; avoid repo root unless explicitly requested.) - Architecture style: layered / hex / clean (pick one) and any hard boundaries (e.g.,
domain/must not importinfra/). - OK to add tooling when missing? (default: yes; Spotless for Java/Kotlin)
- Default commands: format / lint / test for each module (changed-files-first where practical).
Workflow (monorepo-aware)
- Scan for candidate modules and languages.
- Use
scripts/scan_modules.pyto produce a quick inventory. - If
pythonis not available or the script fails, tell the user and ask whether to install Python or proceed with a manual module scan.
- Use
- Propose the nested
AGENTS.mdplacement(s) and get confirmation.- If the only detected module is repo root, suggest a subdir (e.g.,
src/,apps/<name>/,packages/<name>/) or ask the user where the code “starts”.
- If the only detected module is repo root, suggest a subdir (e.g.,
- For each confirmed module root:
- Create/update
<module>/AGENTS.mdusingreferences/agents-template.md. - Fill the
codex-guidelinesJSON block (schema:references/verifiable-block.md) with runnable commands.
- Create/update
- Ensure formatting + linting exist (prefer existing; otherwise add best-practice defaults).
- JVM (Gradle/Maven): add/configure Spotless (see
references/spotless.md). - Others: pick a minimal, common default and wire commands into
AGENTS.md(seereferences/language-defaults.md).
- JVM (Gradle/Maven): add/configure Spotless (see
Deliverable
Provide:
- The list of module roots covered and each
AGENTS.mdcreated/updated. - The
codex-guidelinescommand block per module (format/lint/test). - Any tooling/config changes added (e.g., Spotless) and where they live.