Agents Md Generator

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/managedocs.py / scripts/managedirs.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.

1. 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.

1. 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.

1. 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.

1. 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
• Source: Eriemon/agents-md-generator
• License: Apache-2.0

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