What if Python isn't available or the scan fails?

The tool will prompt to install Python or proceed with a manual module scan.

AGENTS.md is a per-module guidelines document that defines architecture choices, runnable formatting/linting commands, and a verifiable config block.

How does it determine module roots?

It uses the scan_modules.py script to inventory modules and proposes module-level AGENTS.md placements, with manual override if needed.

coding-guidelines-gen

Scanned

npx machina-cli add skill jmerta/codex-skills/coding-guidelines-gen --openclaw

Files (1)

SKILL.md

2.3 KB

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 import infra/).
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.py to produce a quick inventory.
- If python is not available or the script fails, tell the user and ask whether to install Python or proceed with a manual module scan.
Propose the nested AGENTS.md placement(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”.
For each confirmed module root:
- Create/update <module>/AGENTS.md using references/agents-template.md.
- Fill the codex-guidelines JSON block (schema: references/verifiable-block.md) with runnable commands.
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 (see references/language-defaults.md).

Deliverable

Provide:

The list of module roots covered and each AGENTS.md created/updated.
The codex-guidelines command block per module (format/lint/test).
Any tooling/config changes added (e.g., Spotless) and where they live.

Source

git clone https://github.com/jmerta/codex-skills/blob/main/coding-guidelines-gen/SKILL.mdView on GitHub

Overview

Generates nested AGENTS.md files for each module in a monorepo, defining architecture boundaries, formatting/linting commands, and a verifiable config block. It detects languages and tooling, asks for architecture preferences, and sets up missing formatters/linters (Spotless for JVM). This keeps module guidelines consistent and runnable.

How This Skill Works

It scans modules using scripts/scan_modules.py to identify candidate roots. For each confirmed module, it creates or updates module/AGENTS.md from references/agents-template.md and fills in a codex-guidelines block with runnable commands. It then ensures formatting and linting tooling exist (Spotless for JVM) and wires defaults into the per-module guidelines.

When to Use It

You want module-scoped AGENTS.md guidelines for a monorepo.
You need to scan a repo for candidate module roots.
You want to confirm architecture style and boundaries.
You need to add or configure formatters/linters (e.g., Spotless for JVM).
You want runnable format/lint/test commands per module and a verifiable config.

Quick Start

Step 1: Run the scan to identify module roots with scripts/scan_modules.py.
Step 2: Confirm module root placements and architecture preferences.
Step 3: For each confirmed module, create/update AGENTS.md from templates, add the codex-guidelines block, and ensure formatters/linters exist (Spotless for JVM).

Best Practices

Scan and validate module roots before writing AGENTS.md.
Use monorepo-aware placement to avoid repo root unless requested.
Prefer existing templates (references/agents-template.md) for consistency.
Provide runnable, language-aware commands for format, lint, test.
Publish a verifiable config block so the verifier skill can run it.

Example Use Cases

Repo with apps/, services/, and libs/ generates AGENTS.md at apps/foo and services/bar.
Detects Python + JS stack and configures flake8/eslint plus pre-commit.
Adds Spotless for a Java module and integrates with Gradle.
User confirms architecture style (clean) and enforces domain boundaries.
Outputs a summary of module roots covered and updated AGENTS.md list.

Frequently Asked Questions

Add this skill to your agents