---
name: Create AGENTS.md
slug: create-agents-md
category: AI Engineering
description: Creates or refreshes an AGENTS.md for Carbon packages or ERP modules by reading source code, grounding every claim in real functions, tables, and exports. Ideal when adding modules or performing freshness audits.
github: "https://github.com/crbnos/carbon/tree/main/.ai/skills/create-agents-md"
language: TypeScript
stars: 2272
forks: 318
install: "git clone https://github.com/crbnos/carbon"
added: 2026-07-20T06:48:06.511Z
last_synced: 2026-07-20T06:48:06.511Z
canonical_url: "https://dirskills.com/skills/create-agents-md"
---

# Create AGENTS.md

Creates or refreshes an AGENTS.md for Carbon packages or ERP modules by reading source code, grounding every claim in real functions, tables, and exports. Ideal when adding modules or performing freshness audits.

**Install:** `git clone https://github.com/crbnos/carbon`

## README

<!-- Workflow pattern inspired by Open Mercato (MIT License)
     https://github.com/open-mercato/open-mercato
     Copyright (c) 2025-2026 Open Mercato contributors -->

# create-agents-md — generate or refresh an AGENTS.md

Produce a prescriptive AGENTS.md grounded in source. Every claim MUST trace to a
real function name, table name, import path, or file — grep and verify; never
describe what "might" exist.

**Announce at start:** "Using the create-agents-md skill — generating/refreshing
the AGENTS.md for {target}."

## Step 1: Identify the target

- **Package**: `packages/{name}/` → budget ≤100 lines
- **Module**: `apps/erp/app/modules/{name}/` → budget 60–100 lines

## Step 2: Read the actual source

```bash
# Module:
ls apps/erp/app/modules/{name}/
grep -n "^export" apps/erp/app/modules/{name}/{name}.service.ts
grep -n "export const.*=.*z\." apps/erp/app/modules/{name}/{name}.models.ts
grep -rn "\.from(" apps/erp/app/modules/{name}/{name}.service.ts | sed 's/.*\.from("\([^"]*\)").*/\1/' | sort -u
grep -rn "\.rpc(" apps/erp/app/modules/{name}/ | sed 's/.*\.rpc("\([^"]*\)".*/\1/' | sort -u
grep -rn "requirePermissions" apps/erp/app/routes/x+/{name}* | head -10

# Package:
ls packages/{name}/src/
cat packages/{name}/src/index.ts
cat packages/{name}/package.json | jq '.exports'
```

## Step 3: If refreshing, read the existing file

- **Preserve** human-added notes, warnings, and domain explanations.
- **Update** stale function/table/import names (verify each with grep).
- **Add** new exports/tables/patterns; **remove** references to deleted code.

## Step 4: Read the relevant rules

Find the `.ai/rules/` files that govern this area (via the root `AGENTS.md`
Task Router) and reference them in the Rules References section — only files
that actually exist.

## Step 5: Write it

### Module template

````markdown
# {Module Name} Module

{One line: what this module does in the ERP domain.}

## Key Domain Concepts
{3–6 terms a non-manufacturing AI needs. **Term** — plain-English definition.
 Include status lifecycles.}

## Safety
### Always
- MUST {do X} — `{function/table}` depends on it.   {3–5 rules, grounded}
### Ask First
- {action} — {why risky}.                            {2–3 items}
### Never
- {action} — {what breaks}.                          {2–3 items}

## Validation Commands
```bash
pnpm exec turbo run typecheck --filter=erp
pnpm --filter erp test
```

## Key Data Model
| Table / View | Purpose |
|---|---|

## Key Service Functions
- `{functionName}` — {what it does}   {only what another module would call}

## Copy From   {OPTIONAL — only if this module is a good template}
| To build… | Copy from… | Then change… |

## Related Modules
- **{module}** — {integration point}

## Rules References
- `.ai/rules/{file}.md` — {what it covers}
````

### Package template

````markdown
# @carbon/{name}

{One line.}

## Always / Ask First / Never
{Same shape as the module template.}

## Validation Commands
```bash
pnpm --filter @carbon/{name} typecheck
pnpm --filter @carbon/{name} test
```

## Key Exports
| Subpath | Provides |
|---------|----------|
| `.` | {…} |          {real subpaths from package.json exports}

## Cross-References
{rules, related packages, consuming apps}
````

## Done when — verify each line

- [ ] Every function name exists: `grep -n "export.*{name}" {file}` hits
- [ ] Every table name exists: grep in the service file hits
- [ ] Every import path is real (check the barrel / exports field)
- [ ] Every referenced `.ai/rules/` file exists
- [ ] Tone is prescriptive ("MUST use X"), not descriptive ("X is used")
- [ ] Line count within budget; no `{placeholder}` / TBD left
- [ ] Modules: Key Domain Concepts present; Never section present
- [ ] Refresh: human-added notes preserved

## Anti-patterns

- Listing functions you didn't grep for (renamed/deleted ones will lie)
- Abstract architecture prose ("uses a service layer" says nothing)
- Copying a sibling AGENTS.md and renaming — every module has different tables,
  functions, and concepts
- Vague bullets: "Services handle data access" ❌ vs
  "MUST use `insertManualInventoryAdjustment` for quantity changes — it creates
  ledger entries and updates tracked entities" ✅