generate-agents-md 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 generate-agents-md contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# generate-agents-md
+
+`generate-agents-md` 是一个适用于 Codex 和 Claude Code 的 skill，用来为任意代码仓库生成或更新项目专属的 `AGENTS.md`。
+
+它采用 `SKILL.md` 目录结构发布。Codex 和 Claude Code 都可以读取这种以 Markdown 指令为核心的 skill 形式。
+
+它的核心思想很简单：
+
+```text
+用户的开发偏好 + 代码库里的真实事实 = 可执行的 AGENTS.md
+```
+
+## 背景
+
+AI 编程工具越来越强，但一个常见问题是：每次进入新项目，AI 都需要重新理解项目结构、技术栈、命令、边界和团队偏好。
+
+如果没有清晰的 `AGENTS.md`，AI 很容易：
+
+- 臆造不存在的命令、端口或目录
+- 把多个独立项目误当成 monorepo
+- 跨项目引入不该共享的代码
+- 忽略已有公共模块、组件或工具函数
+- 跑错测试命令，或者干脆不验证
+- 生成一堆泛泛而谈、无法执行的项目规范
+
+手动为每个项目写 `AGENTS.md` 又很麻烦。尤其当你经常切换项目、维护多个仓库，或者希望把自己的开发习惯沉淀成可复用工作流时，这件事会变成重复劳动。
+
+所以我们做了 `generate-agents-md`。
+
+## 它解决什么问题
+
+这套工作流会指导 AI agent 先读取用户要求，再阅读仓库事实，最后生成真正贴合项目的 `AGENTS.md`。
+
+它适用于：
+
+- 前端项目
+- 后端项目
+- 全栈项目
+- 工具库
+- 单体仓库
+- monorepo
+- 多个独立项目放在一起的仓库
+
+它关注的不是“写一份漂亮文档”，而是生成一份未来 AI agent 能照着工作的项目说明。
+
+## 优点
+
+- **通用**：不绑定前端、后端或某个框架。
+- **用户要求优先**：先保留你的开发偏好，再用代码库事实补全。
+- **基于证据**：命令、端口、目录、框架和边界都来自仓库文件，不鼓励臆造。
+- **支持多项目**：能判断是单项目、monorepo，还是多个独立项目放在一起。
+- **支持嵌套说明**：只有当子项目确实有不同命令、技术栈或边界时，才建议生成 nested `AGENTS.md`。
+- **短而可执行**：避免把 `AGENTS.md` 写成空泛的工程学长文。
+- **尊重已有规范**：更新已有 `AGENTS.md` 时，会尽量保留有价值的内容。
+
+## 安装
+
+### Codex
+
+使用 Node / npx 安装到 Codex：
+
+```bash
+npx github:<owner>/generate-agents-md --target codex
+```
+
+安装后重启 Codex。
+
+也可以使用 Codex skill installer：
+
+```bash
+python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo <owner>/generate-agents-md \
+  --path skills/generate-agents-md
+```
+
+安装后重启 Codex。
+
+### Claude Code
+
+Claude Code 会读取 `~/.claude/skills/<skill-name>/SKILL.md` 形式的用户级 skill。安装到 Claude Code：
+
+```bash
+npx github:<owner>/generate-agents-md --target claude-code
+```
+
+安装后重启 Claude Code。
+
+### 同时安装到 Codex 和 Claude Code
+
+```bash
+npx github:<owner>/generate-agents-md --target both
+```
+
+### 本地开发安装
+
+```bash
+git clone https://github.com/<owner>/generate-agents-md.git
+cd generate-agents-md
+node scripts/install.mjs --target codex
+node scripts/install.mjs --target claude-code
+```
+
+如果以后发布到 npm，也可以使用：
+
+```bash
+npx generate-agents-md --target codex
+```
+
+## 使用方式
+
+在 Codex 中：
+
+```text
+Use $generate-agents-md to generate AGENTS.md for this repository.
+
+My requirements:
+- keep instructions concise
+- do not invent commands
+- preserve existing project conventions
+- create nested AGENTS.md files only when subprojects have different commands or boundaries
+```
+
+在 Claude Code 中，可以直接让 Claude 使用已安装的 skill：
+
+```text
+Use the generate-agents-md skill to generate AGENTS.md for this repository.
+```
+
+中文也可以：
+
+```text
+使用 generate-agents-md skill 给这个仓库生成 AGENTS.md。
+
+我的要求：
+- 多个项目要分开写
+- 不要臆造命令和端口
+- 保留已有项目规范
+- 改完要写清楚验证方式
+```
+
+## 仓库结构
+
+```text
+.
+└── skills/
+    └── generate-agents-md/
+        ├── SKILL.md
+        └── agents/
+            └── openai.yaml
+```
+
+## 许可证
+
+MIT
+
+---
+
+# generate-agents-md
+
+`generate-agents-md` is a skill for Codex and Claude Code that generates or updates project-specific `AGENTS.md` files for any codebase.
+
+It is distributed as a `SKILL.md` directory. Codex and Claude Code can both use this Markdown-first skill format.
+
+The core idea is simple:
+
+```text
+User development preferences + repository facts = actionable AGENTS.md
+```
+
+## Background
+
+AI coding tools are becoming more capable, but they still face a recurring problem: every time they enter a new repository, they need to rediscover the project structure, stack, commands, boundaries, and team preferences.
+
+Without a clear `AGENTS.md`, AI agents can easily:
+
+- invent commands, ports, or directories
+- mistake colocated independent projects for a monorepo
+- import code across boundaries that should remain separate
+- ignore existing shared modules, components, or helpers
+- run the wrong validation command, or skip validation entirely
+- produce generic project rules that are not actually useful
+
+Writing `AGENTS.md` manually for every project is repetitive. This is especially painful when you switch between many repositories or want to turn your development habits into a reusable workflow.
+
+That is why `generate-agents-md` exists.
+
+## What It Solves
+
+This workflow guides an AI agent to capture the user's requirements first, inspect the repository second, and then generate an `AGENTS.md` that fits the actual project.
+
+It works for:
+
+- frontend projects
+- backend projects
+- full-stack projects
+- libraries
+- single-project repositories
+- monorepos
+- repositories that colocate several independent projects
+
+The goal is not to write pretty documentation. The goal is to create instructions that future AI coding agents can actually follow.
+
+## Strengths
+
+- **Generic**: not tied to frontend, backend, or a specific framework.
+- **User-first**: preserves your development preferences before filling in repository-specific details.
+- **Evidence-based**: commands, ports, directories, frameworks, and boundaries should come from repository files.
+- **Multi-project aware**: can distinguish between a single project, a monorepo, and colocated independent projects.
+- **Nested instructions when useful**: only suggests nested `AGENTS.md` files when subprojects have meaningfully different commands, stacks, or boundaries.
+- **Concise and operational**: avoids turning `AGENTS.md` into a long essay of generic engineering advice.
+- **Respectful of existing docs**: preserves useful content when updating an existing `AGENTS.md`.
+
+## Install
+
+### Codex
+
+Install into Codex with Node / npx:
+
+```bash
+npx github:<owner>/generate-agents-md --target codex
+```
+
+Restart Codex after installing the skill.
+
+You can also use the Codex skill installer:
+
+```bash
+python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo <owner>/generate-agents-md \
+  --path skills/generate-agents-md
+```
+
+Restart Codex after installing the skill.
+
+### Claude Code
+
+Claude Code reads user-level skills from `~/.claude/skills/<skill-name>/SKILL.md`. Install into Claude Code:
+
+```bash
+npx github:<owner>/generate-agents-md --target claude-code
+```
+
+Restart Claude Code after installing the skill.
+
+### Install into both Codex and Claude Code
+
+```bash
+npx github:<owner>/generate-agents-md --target both
+```
+
+### Local development install
+
+```bash
+git clone https://github.com/<owner>/generate-agents-md.git
+cd generate-agents-md
+node scripts/install.mjs --target codex
+node scripts/install.mjs --target claude-code
+```
+
+If this package is later published to npm, you can use:
+
+```bash
+npx generate-agents-md --target codex
+```
+
+## Usage
+
+In Codex:
+
+```text
+Use $generate-agents-md to generate AGENTS.md for this repository.
+
+My requirements:
+- keep instructions concise
+- do not invent commands
+- preserve existing project conventions
+- create nested AGENTS.md files only when subprojects have different commands or boundaries
+```
+
+In Claude Code, ask Claude to use the installed skill:
+
+```text
+Use the generate-agents-md skill to generate AGENTS.md for this repository.
+```
+
+Chinese prompts work too:
+
+```text
+使用 generate-agents-md skill 给这个仓库生成 AGENTS.md。
+
+我的要求：
+- 多个项目要分开写
+- 不要臆造命令和端口
+- 保留已有项目规范
+- 改完要写清楚验证方式
+```
+
+## Repository Layout
+
+```text
+.
+└── skills/
+    └── generate-agents-md/
+        ├── SKILL.md
+        └── agents/
+            └── openai.yaml
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "generate-agents-md",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Install the generate-agents-md skill for Codex or Claude Code.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "generate-agents-md": "./scripts/install.mjs"
+  },
+  "files": [
+    "scripts/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "codex",
+    "claude-code",
+    "skill",
+    "agents.md",
+    "ai-agent",
+    "ai-coding",
+    "developer-tools"
+  ]
+}

package/scripts/install.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = resolve(__dirname, '..');
+const skillName = 'generate-agents-md';
+const sourceDir = join(rootDir, 'skills', skillName);
+const args = process.argv.slice(2);
+
+function readTarget() {
+  const targetIndex = args.findIndex((arg) => arg === '--target' || arg === '-t');
+  if (targetIndex !== -1) {
+    return args[targetIndex + 1];
+  }
+
+  const inlineTarget = args.find((arg) => arg.startsWith('--target='));
+  if (inlineTarget) {
+    return inlineTarget.split('=')[1];
+  }
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  return 'codex';
+}
+
+function printHelp() {
+  console.log(`Usage:
+  generate-agents-md [--target codex|claude-code|both]
+
+Targets:
+  codex        Install to $CODEX_HOME/skills or ~/.codex/skills
+  claude-code  Install to ~/.claude/skills
+  both         Install to both locations
+`);
+}
+
+function installTo(targetDir) {
+  const skillsDir = dirname(targetDir);
+  mkdirSync(skillsDir, { recursive: true });
+  rmSync(targetDir, { recursive: true, force: true });
+  cpSync(sourceDir, targetDir, { recursive: true });
+  console.log(`Installed ${skillName} to ${targetDir}`);
+}
+
+if (!existsSync(sourceDir)) {
+  console.error(`Skill source not found: ${sourceDir}`);
+  process.exit(1);
+}
+
+const target = readTarget();
+const codexHome = process.env.CODEX_HOME || join(homedir(), '.codex');
+const codexTarget = join(codexHome, 'skills', skillName);
+const claudeTarget = join(homedir(), '.claude', 'skills', skillName);
+
+if (!['codex', 'claude-code', 'both'].includes(target)) {
+  console.error(`Unknown target: ${target}`);
+  printHelp();
+  process.exit(1);
+}
+
+if (target === 'codex' || target === 'both') {
+  installTo(codexTarget);
+}
+
+if (target === 'claude-code' || target === 'both') {
+  installTo(claudeTarget);
+}
+
+console.log(target === 'claude-code' ? 'Restart Claude Code to pick up the new skill.' : 'Restart Codex or Claude Code to pick up the new skill.');

package/skills/generate-agents-md/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: generate-agents-md
+description: Generate or update AGENTS.md files for any codebase by combining explicit user requirements with repository facts, including project boundaries, commands, conventions, tooling, validation workflows, and nested project instructions. Use when the user wants reusable agent instructions for a new or existing project.
+---
+
+# Generate AGENTS.md
+
+Use this skill to create concise, project-specific `AGENTS.md` files. The goal is to turn the user's preferences plus the repository's actual conventions into instructions a future coding agent can follow.
+
+## Core Principle
+
+User requirements are first-class constraints. Repository facts refine and ground those requirements. Do not invent commands, ports, architecture, tools, or conventions.
+
+## Workflow
+
+1. Capture the user's explicit requirements before reading too much into the codebase.
+2. Inspect the repository shape with fast tools such as `rg --files`, `find`, and package/config reads.
+3. Determine project boundaries:
+   - single project
+   - true workspace or monorepo
+   - several independent projects colocated together
+   - library, application, service, or mixed repository
+4. Read representative evidence:
+   - root README and docs
+   - manifests such as `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `.csproj`
+   - framework/build configs
+   - test, lint, formatter, CI, and container configs
+   - source entry points, routing, shared modules, packages, apps, services, or libraries
+   - existing `AGENTS.md`, `CONTRIBUTING.md`, coding standards, or architecture docs
+5. Identify practical instructions:
+   - project purpose and stack
+   - install/dev/build/test/lint/typecheck commands
+   - local ports and services when present
+   - important entry files and directories
+   - reusable modules, components, packages, helpers, or APIs
+   - generated/cache/vendor directories to avoid
+   - dependency and cross-boundary rules
+   - validation expectations and how to report failures
+6. Decide file placement:
+   - Use one root `AGENTS.md` when the repository has one coherent project.
+   - Use a short root `AGENTS.md` plus nested `AGENTS.md` files when subprojects have different commands, stacks, ownership boundaries, or conventions.
+   - Do not create nested files just because directories exist.
+7. Write or update the files.
+8. Summarize generated files, key assumptions, and any facts that could not be verified.
+
+## Content Shape
+
+Prefer these sections when relevant:
+
+- Project Context
+- Work Boundaries
+- Important Entrypoints
+- Reuse Priorities
+- Coding Rules
+- Styling or Architecture Rules
+- Data, API, or Dependency Rules
+- Commands and Validation
+- Local Ports or Services
+- Files to Avoid
+
+Keep each `AGENTS.md` operational and compact. Avoid generic advice unless the user asked for it or the repository clearly supports it.
+
+## User Requirements Handling
+
+Preserve user preferences such as:
+
+- coding style and architecture preferences
+- testing or review expectations
+- UI/design rules
+- dependency restrictions
+- security, performance, or accessibility expectations
+- generated-file handling
+- forbidden operations
+- multi-project boundaries
+
+If a user requirement conflicts with repository evidence, do not silently resolve it. Explain the conflict and choose the safer, less destructive option.
+
+## Detection Guidance
+
+- If a root workspace file exists, treat the repository as a workspace unless project files show the apps are intentionally independent.
+- If subdirectories each have their own manifest and lockfile, consider whether they are colocated independent projects.
+- Commands should come from manifests, Makefiles, task runners, CI, docs, or obvious framework conventions. Mark uncertain items as not found instead of inventing them.
+- Local ports should come from config files, scripts, docs, compose files, or environment examples.
+- Generated folders such as `node_modules`, `.next`, `dist`, `build`, `.turbo`, `.umi`, `target`, `.venv`, `__pycache__`, and coverage output should usually be excluded from inspection and editing.
+
+## Quality Bar
+
+Good `AGENTS.md` files are:
+
+- specific to the repository
+- short enough to be read every time
+- clear about boundaries and commands
+- grounded in evidence
+- faithful to the user's requirements
+- useful for day-to-day coding, review, testing, and maintenance
+
+Avoid:
+
+- long essays
+- generic best-practice dumps
+- invented commands or ports
+- broad rewrite instructions unless the user asked for them
+- duplicating the same detailed rules in every nested file
+- overwriting existing project instructions without preserving useful content

package/skills/generate-agents-md/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Generate AGENTS.md"
+  short_description: "Create repo-specific agent instructions."
+  default_prompt: "Use $generate-agents-md to generate or update AGENTS.md from my requirements and this repository's conventions."