# Agents Md Generator

> Use when creating, updating, verifying, or reviewing AGENTS.md files and AI coding-agent rule files; when a project or current work folder root lacks AGENTS.md; when root AGENTS.md version metadata is missing or mismatched; when the user explicitly mentions AGENTS.md, agent rules, or scoped AGENTS.md; or when the user is talking about the current workspace/current repository/current work folder a…

- **Type:** Skill
- **Install:** `agentstack add skill-eriemon-agents-md-generator-agents-md-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Eriemon](https://agentstack.voostack.com/s/eriemon)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Eriemon](https://github.com/Eriemon)
- **Source:** https://github.com/Eriemon/agents-md-generator

## Install

```sh
agentstack add skill-eriemon-agents-md-generator-agents-md-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AGENTS.md Generator

Create operational context files for AI coding agents. Use facts from the repository first, ask only for missing human policy, and verify before claiming the draft is ready.

当用户明确提到 `AGENTS.md`、`agent rules`、`scoped AGENTS.md` 时，直接进入本技能。

当用户在当前工作区、当前工程、当前仓库、或当前工作文件夹语境里说“计划”、“规划”或“准备”时，也要进入本技能，但第一步不是直接设计，而是先检查当前工作文件夹根 `AGENTS.md` 状态。

当前工作区类请求除了检查当前工作文件夹根 `AGENTS.md`，还要检查全局 `~/.codex/AGENTS.md` 或 `$CODEX_HOME/AGENTS.md` 是否存在且包含受管的全局基线区块。这个全局文件只负责跨仓库默认行为和入口习惯；仓库阈值、脚本布局、路径例外、长任务细节和发布规则继续由最近的项目 `AGENTS.md` 或 repository governance 配置承载。

全局 `~/.codex/AGENTS.md` v3 基线还负责跨工作区的轻量任务入口习惯：优先复用现有仓库模式、工具、库、模板和成熟开源项目；仅在 repository governance 提供 `task_rating_gate.py` 且任务复杂度足以影响执行模式时使用它，并把输出视为 advisory。不要为每个任务固定询问难度或规模；只有范围、接口、数据、安全、成本、不可逆动作或生产依赖会被答案实质影响时才询问用户。

全局 `~/.codex/AGENTS.md` v3 基线还必须包含英文 `Coding Behavior Baseline` 兼容标题：要求代理基于仓库证据思考，优先选择最小可行实现，只做与请求、集成和验证直接相关的外科式改动，并把任务转成可验证目标后循环验证。该章节保留四段纪律、`Done When`、以及禁止伪造测试、输出或验证证据的诚信规则。

全局 `~/.codex/AGENTS.md` v3 基线还包含 `Comments And Documentation`：注释公共契约、关键不变量、非显然决策、生成边界和风险边界；不要复述显然语法；行为变化时同步更新旧注释和文档。语言专用技能路由属于 `Coding Behavior Baseline`：Python 优先 `readable-python-generator`，bat/cmd、shell/bash、PowerShell、Tcl 脚本优先 `readable-script-generator`。仓库根 `AGENTS.md` 和本地治理配置继续承载更具体的语言细则。

全局 `~/.codex/AGENTS.md` 基线还要求保护已安装 skill 内容：未经用户明确许可，不要修改 `$CODEX_HOME/skills`、`~/.codex/skills` 或等效安装目录中的 installed skill；只有用户明确授权安装、替换或直接编辑时才允许修改。

全局 `~/.codex/AGENTS.md` v3 基线还包含 `Environment And Dependency Safety`：先识别并使用仓库既有环境、包管理器和依赖流程；安装 Python 依赖或运行长驻 Python 服务前确保项目隔离环境已激活；远程服务器优先使用仓库配置环境，否则在远程工作区下创建隔离环境；禁止改系统 Python、conda `base`、全局或 user site-packages、`sudo pip`、未激活环境的 `pip install` 或 `pip install --user`。

全局 `~/.codex/AGENTS.md` v3 基线还包含简短 Markdown documentation formulas 约束：写 Markdown 文档中的数学公式时使用 inline `$...$` 或 block `$$...$$` 语法；该规则不约束代码字符串、测试 fixture、日志样本、转义示例或非文档文本。

入口路由要显式区分 4 类任务：`read_only`（解释、分析、规划、现状检查、只读 review）、`design`（收集/修订答案但尚未申请写入）、`write`（正式生成或更新 AGENTS 控制档案）、`governance_high_risk`（release/merge 前治理审查）。只有 `write` 和 `governance_high_risk` 可以触发审查子智能体；`read_only` 明确禁止。

当根 `AGENTS.md` 通过 `default_language` 把默认自然语言回复锁定为某种语言时，这个约束也必须覆盖 Plan Mode：若代理输出 ``，标签内的方案正文必须使用该默认语言，除非用户显式切换语言；`` 标签本身保持原样，代码、命令、日志、原始错误文本和专有名词可保留原文。

如果用户明确要求创建、更新、审查或修复 `AGENTS.md` / `agent rules` / `scoped AGENTS.md`，先检查根 `AGENTS.md`，然后继续进入完整设计访谈或更新流程；不要因为根文件健康就提前停止。只有当前工作区类“计划 / 规划 / 准备”探测入口在根 `AGENTS.md` 正常时才只报告“检查通过”。

根 `AGENTS.md` 缺失或缺少版本元数据时，先报告异常原因，然后进入完整设计访谈。只有根 `AGENTS.md` 的 `agents_version` 或 `generator_version` 与当前已安装 `agents-md-generator` 版本不一致，并且当前工作文件夹已经有落地内容时，才允许进入最小 takeover 兼容流程。

如果全局 `.codex/AGENTS.md` 缺失、为空、或缺少受管基线区块，不要静默忽略；要明确报告“全局入口规则未落盘”，并给出 `python skills/agents-md-generator/scripts/python/docs/manage_docs.py sync-global-codex-agents . --write` 作为修复命令。

如果是“已有内容但无根 `AGENTS.md`”的工作文件夹，除了结构检查之外，还要读取精确匹配当前工作目录的 Codex sessions：只接受 `.codex/sessions` 中 `session_meta.payload.cwd` 规范化后与当前工作目录完全一致的会话。v1.1.0 起不再生成 `docs/experience/`；长期项目记忆统一进入 `docs/memory/`，旧 `docs/experience/` 只作为未治理历史数据保留。

如果用户明确要求进行 Codex Token 用量统计，例如直接要求“统计 Codex token usage / Token 用量 / token 消耗”，走只读工具分支：直接运行 `python skills/agents-md-generator/scripts/python/detect/codex_token_usage_review.py --hours 48`，按用户要求决定是否附加 `--verbose` 或 `--json`，不要进入 AGENTS 设计访谈。这个分支只在当前环境可解析到 `$CODEX_HOME/sessions` 或 `~/.codex/sessions` 且目录存在时执行；如果检测不到 Codex sessions 目录，要明确拒绝执行并说明原因。`--sessions-root` 只允许等于或位于当前 Codex sessions 根目录之下，用于测试或诊断时也不能跳出当前 Codex sessions 树。泛化的成本、优化、会话健康、/status 建议等问题不算显式触发。

外部工作区生成的 AGENTS/docs 治理命令必须调用已安装的 `agents-md-generator` 运行时，例如 `python /skills/agents-md-generator/scripts/python/docs/manage_docs.py ...`。不要把这些 governance runtime 脚本写成目标项目自己的 project-local scripts/manage_docs.py / scripts/manage_dirs.py，也不要为了让命令可执行而把本 skill 的脚本复制进目标工作区。只有 `agents-md-generator` owner repo 自身允许继续使用 repo-local `python skills/agents-md-generator/scripts/python/...` 自举路径。

## Pipeline

1. **Detect**
   - Run `python skills/agents-md-generator/scripts/python/detect/inspect_project.py ` to gather language, framework, package manager, CI, AI configs, files, and directories.
   - If `root_agents_md_exists` is false, or the root `AGENTS.md` is missing `agents_version` or `generator_version`, or either version does not match the current local installed `agents-md-generator` version, treat the workspace as trigger-required/rebuild-required.
   - Inspect the global `.codex/AGENTS.md` baseline status too. If it is missing, empty, unmanaged, or outdated, report the exact reason and recommend `python skills/agents-md-generator/scripts/python/docs/manage_docs.py sync-global-codex-agents . --write`; the managed v3 baseline must include the `baseline_version=3` meta comment, reuse-first behavior, advisory `task_rating_gate.py` routing, the English `Coding Behavior Baseline` title with four discipline sections, `Done When`, and lightweight language skill routing for `readable-python-generator` / `readable-script-generator`, `Comments And Documentation` without skill-selection rules, environment and dependency safety with isolated environment protection, explicit installed skill modification protection, and the short Markdown documentation formulas rule using `$...$` / `$$...$$`.
   - When the user says `计划`, `规划`, or `准备` in the current workspace/current repository/current work folder context, do this root-AGENTS check first. These are trigger entries for inspection routing, not a bypass around the AGENTS.md check.
   - If the root check passes during a current-workspace/current-repository/current-work-folder `计划` / `规划` / `准备` trigger, report that the current work folder root `AGENTS.md` check passed and stop. If the user explicitly asked to create, update, review, or repair AGENTS governance, continue into the full design/update flow instead of stopping.
   - If the root check fails because the root `AGENTS.md` is missing, missing `agents_version`, or missing `generator_version`, report the exact abnormal reason and continue into the full design interview.
   - If the root check fails because `agents_version` or `generator_version` is version-mismatched in an old workspace with landed content, switch to takeover handling instead of the full design interview: minimize identity questions to project type, project/skill name, and default conversation language, but do not skip the structured directory-contract interview. Takeover must still collect local structure, remote structure, feature-placement rules, and any required remote runtime policy before AGENTS.md can be written.
   - If the workspace already has landed content but no root `AGENTS.md`, mark session bootstrap as required, inspect exact-cwd Codex session history, and prepare forced local workspace takeover before normal AGENTS generation continues.
   - Run `python skills/agents-md-generator/scripts/python/detect/detect_scopes.py ` to find directories that may need scoped AGENTS.md files.

2. **Design Interview**
   - Start grouped interviews with `python skills/agents-md-generator/scripts/python/design/collect_design_profile.py  --start`; use `--intent read_only` for explanation, analysis, planning, current-state checks, or read-only review, and keep the default write intent only when the user is actually preparing to write/update governed control files. `--start` should enter takeover mode automatically only for version-mismatched old workspaces with landed content. Missing root files or missing version metadata must stay on the full grouped interview. If `.agents/design-interview-state.json` already exists and is unfinished, resume it instead of silently starting over.
   - Use `python skills/agents-md-generator/scripts/python/design/collect_design_profile.py  --start-takeover` or `--resume-takeover` only when the root `AGENTS.md` is version-mismatched for an old workspace and you need the forced takeover path explicitly.
   - Use `python skills/agents-md-generator/scripts/python/design/collect_design_profile.py  --resume` whenever an earlier design interview is still incomplete.
   - Submit one group at a time with `python skills/agents-md-generator/scripts/python/design/collect_design_profile.py  --answer-file partial.json`.
   - Ask every returned question in the current group and present each returned `options` list to the user. Prefer `request_user_input` when available so the user can choose an option or enter a custom answer.
   - Question `32` for `default_conversation_language` is mandatory for every AGENTS generation or takeover-restructure flow. Do not skip it, infer it, or silently fall back to `中文`.
   - Question `45` for `use_remote_server` is mandatory for every AGENTS generation or takeover-restructure flow. If the user enables remote servers, do not continue until the remote dependency, configuration, task-route mapping, and validation gates are complete.
   - Skill development groups are `[1,32,45]`, `[50,51,52,53,54]`, `[2,3,4]`, `[5,6,7]`, `[8,9,10]`, `[22,23,24]`, `[25,26,27]`, `[28,29,30]`, `[31]`, `[42,43,44,46,47,48,49]`, `[20,21]`.
   - Engineering development groups are `[1,32,45]`, `[50,51,52,53,54]`, `[11,12,13]`, `[14,15,16]`, `[17,18,19]`, `[33,34,35]`, `[36,37,38]`, `[39,40,41]`, `[42,43,44,46,47,48,49]`, `[20,21]`.
   - After each answer group, show the returned `review_summary` and `confirmed_so_far`, then ask the `confirmation_question`. If the user answers no, keep the interview on that same group until the group is re-confirmed.
   - After all grouped interview questions are confirmed, ask whether the user has extra requirements. Record `extra_requirements="none"` when there is no supplement; otherwise write the user's supplement into the control profile and rendered Control Profile.
   - After the final full-design alignment, `--intent read_only` must stop at a read-only completed state, retain `answers_snapshot` plus `profile_preview`, and must not generate `design_review_request` or spawn a review subagent.
   - After the final full-design alignment, write intent must spawn a new review subagent to review the complete answers and profile. Submit its structured `design_review` JSON with `reviewer_type="subagent"`, `verdict`, `findings`, `required_user_confirmations`, `reviewed_answers_hash`, `reviewed_profile_hash`, and `review_summary`.
   - If the subagent rejects the design or returns any `required_user_confirmations`, stop in rework mode, ask the user to confirm the correction items, apply corrections, clear the old review/hash, and repeat final alignment plus subagent review before writing.
   - New and existing projects both must answer the directory-contract group `[42,43,44,46,47,48,49]`; do not skip local, remote, feature-directory, remote conda, or remote runtime archive rules for new work.
   - The remote directory policy fields (`46-49`) are formal write gates whenever `use_remote_server=true` or `remote_directory_structure != not configured`. They may be stored as disabled only when remote structure is explicitly not configured.
   - When remote directory policy is enabled, reject dangerous templates before write: remote conda and runtime path templates must stay relative to the remote workspace root, and they must not contain `..`, wildcards, unsafe shell characters, empty values, or repeated separators such as `//`.
   - A grouped interview is not complete until `extra_requirements` is recorded and the final `alignment_confirmed` confirmation succeeds. Write intent additionally requires an approved subagent `design_review` with matching hashes before `--write`; read-only intent must stop short of that review gate until the caller explicitly runs `python skills/agents-md-generator/scripts/python/design/collect_design_profile.py  --enter-write-review`. Takeover mode may still auto-synthesize non-directory descriptive fields after the minimum identity answers, but it must not auto-confirm final alignment, skip the extra-requirements question, bypass the write-intent review gate, or auto-fill the directory contract.
   - Unfinished interview chains must be resumed or explicitly abandoned with `python skills/agents-md-generator/scripts/python/design/collect_design_profile.py  --reset-interview`.
   - Save answers to JSON only after the full design is aligned and the approved subagent design review is attached. Set `alignment_confirmed=true` only after user yes/no confirmation succeeds, then run `python skills/agents-md-generator/scripts/python/design/collect_design_profile.py  --answers  --write` before claiming strong-control AGENTS.md generation.
   - `--answers  --write` must reject missing `default_conversation_language`, missing explicit `use_remote_server`, missing `extra_requirements`, and any missing, non-subagent, rejected, confirmation-pending, or hash-mismatched `design_review`; batch writes are formal generation flows and must not rely on implicit defaults or unreviewed alignment.
   - If `use_remote_server=yes`, first check whether `erie-remote-ssh` is installed. If it is missing, ask whether to install it from `https://github.com/Eriemon/remote-ssh.git` with install spec `skill=erie-remote-ssh`, `source_path=.`, `dest_name=erie-remote-ssh`.
   - If `use_remote_server=yes` and `erie-remote-ssh discover` reports no configured or enabled server list, ask whether to configure remote servers. Guided configuration uses `remote_ssh.py configure --interactive`; manual configuration remains blocked until the user finishes setup and resumes.
   - If `use_remote_server=yes` and `erie-remote-ssh choices` returns selectable servers, require explicit user task-route mapping even when there is only one enabled server. Each route must include `task_name` plus `primary_server_id`, may include `fallback_server_ids`, and every referenced server must pass `check` plus `workspace-check` before the route can be written into AGENTS.md.
   - When a route omits explicit route tasks, fall back to the selected primary server `functions` so the rendered contract never leaves responsibilities empty.
   - For user-developed Skills, require `skills//SKILL.md`; the frontmatter `name` must exactly match the folder name and use only lowercase letters, digits, and hyphens. Reject root-level self-hosted skill folders such as `//SKILL.md`.
   - For engineering projects, require `engineering//` as the project directory contract; do not accept root-level engineering application folders.

3. **Extract**
   - Run `python skills/agents-md-generator/scripts/python/detect/extract_commands.py ` to collect command candidates from Makefile, package.json, pyproject.toml, composer.json, go.mod, and visible CI workflow `run:` lines.
   - Run `python skills/agents-md-generator/scripts/python/detect/extract_context.py ` to collect docs, ADRs, utilities, quality configs, agent configs, golden sample candidates, and CI rules.
   - Read `references/agents-md-guidance.md` for section choices and what belongs in AGENTS.md.
   - Read `references/skill-design-coverage.md` when generating or reviewing AGENTS.md for Skill development.
   - Read `references/capability-coverage.md` when comparing this skill to other AGENTS.md generator implementations.
   - Read `references/book-rules-coverage.md` before using book-derived engineering rule sets; choose one primary rule set and keep full material out of AGENTS.md.
   - Run `python skills/agents-md-generator/scripts/python/release/select_engineering_rules.py --list` or `--task ` when the user wants book-derived engineering guidance.

4. **Ask Missing Intent**
   - Ask only for preferences that cannot be discovered from files: commit policy, risky operations, approval boundaries, expensive checks, and domain terminology.
   - Use `references/question-bank.md` for focused questions.

5. **Generate**
   - Run `python skills/agents-md-generator/scripts/python/render/render_agents.py  --profile /.agents/agents-control.json` first; default is dry-run.
   - Use `--write` only after reviewing the draft and confirming the target path is inside the intended repository.
   - For strong-control external wo

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Eriemon](https://github.com/Eriemon)
- **Source:** [Eriemon/agents-md-generator](https://github.com/Eriemon/agents-md-generator)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-eriemon-agents-md-generator-agents-md-generator
- Seller: https://agentstack.voostack.com/s/eriemon
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.