agents-md

分类: 工具与效率 | 上传者: charliesbot | 下载: 0 | 版本: v1.0（最新）

改进或创建 AGENTS.md 文件，作为 AI 编码代理（Claude、Gemini 等）的共享指令。每当用户提到 AGENTS.md、CLAUDE.md、GEMINI.md、代理指令、代理配置或想要改进 AI 代理在其项目中的行为方式时，请使用此技能。当用户说“改进我的指令”、“代理文件”、“更新我的规则”或询问配置编码代理的最佳实践时也会触发。如果有疑问并且任务涉及 AI 代理指令文件，请使用此技能。 --- 您帮助用户编写和改进 AGENTS.md 文件 - AI 编码代理（Claude、Gemini 等）在每次会话开始时读取的共享指令文件。目标是通过符号链接跨平台工作的单个文件。在分析或编写任何 AGENTS.md 内容之前，请阅读“references/BEST_PRACTICES.md”。它包含从官方文档中提取的模式，为下面的每个决策提供信息。 ## 核心工作流程 ### 1. 评估当前状态在提出更改建议之前，请阅读目标文件并根据以下维度对其进行评估： - **长度** — 是否低于 200 行？最好在100以下？代理的预算为约 150 条他们可以可靠遵循的指令，并且系统提示已使用约 50 条指令。 - **结构** — 它是否使用 markdown 标题来对相关指令进行分组？或者它是一堵文字墙/一个巨大的列表？ - **特异性** - 指令是具体且可验证的（“使用 2 个空格缩进”）还是模糊的（“编写干净的代码”）？ - **矛盾** — 任何规则是否相互冲突？ - **范围混合** — 是否将个人偏好与项目级标准融合在一起？ - **信噪比** — 每条指令是否都通过了简洁性测试（“删除这条指令会导致代理犯错误”）？是否存在代理在未经告知的情况下仍会遵循的指示？ - **完整性** - 是否缺少关键部分（优先级、从不/硬性规则、通用命令、架构、工作流程、工具）？分数：1 = 全部出席，2 = 1-2 缺席

更新日志: Source: GitHub https://github.com/charliesbot/chai

目录结构

当前层级: tree/main/skills/agents-md/

📁 references/
- 📄 BEST_PRACTICES.md 14.1 KB
📁 scripts/
- 📁 lib/
  - 📄 parse.ts 5.3 KB
- 📄 discover.sh 4.2 KB
📄 SKILL.md 7.8 KB

SKILL.md

---
name: agents-md
description: >
  Improve or create AGENTS.md files that serve as shared instructions for AI coding agents
  (Claude, Gemini, etc.). Use this skill whenever the user mentions AGENTS.md, CLAUDE.md,
  GEMINI.md, agent instructions, agent configuration, or wants to improve how AI agents
  behave in their project. Also trigger when the user says "improve my instructions",
  "agents file", "update my rules", or asks about best practices for configuring coding agents.
  If in doubt and the task involves AI agent instruction files, use this skill.
---

You help users write and improve AGENTS.md files — shared instruction files that AI coding agents (Claude, Gemini, etc.) read at the start of every session. The goal is a single file that works across platforms via symlinks.

Read `references/BEST_PRACTICES.md` before analyzing or writing any AGENTS.md content. It contains the patterns extracted from official documentation that inform every decision below.

## Core Workflow

### 1. Assess the Current State

Before proposing changes, read the target file and evaluate it against these dimensions:

- **Length** — is it under 200 lines? Ideally under 100? Agents have a budget of ~150 instructions they can reliably follow, and the system prompt already uses ~50.
- **Structure** — does it use markdown headers to group related instructions? Or is it a wall of text / a single giant list?
- **Specificity** — are instructions concrete and verifiable ("use 2-space indentation") or vague ("write clean code")?
- **Contradictions** — do any rules conflict with each other?
- **Scope mixing** — does it blend personal preferences with project-level standards?
- **Signal-to-noise** — does every instruction pass the conciseness test ("would removing this cause the agent to make mistakes")? Are there instructions the agent would follow anyway without being told?
- **Completeness** — is it missing key sections (Priorities, Never/Hard Rules, Common Commands, Architecture, Workflow, Tooling)? Score: 1 = all present, 2 = 1-2 missing, 3 = 3+ missing.

### 1b. Exit Gate

After scoring, determine whether to proceed or stop:

- **Score 7–8 (healthy):** Report the assessment, state "No changes recommended," and STOP. Do not propose a patch or refactor.
- **Score 9–12 (minor issues):** Present findings and ask the user if they want changes. Do not propose a patch unless the user confirms.
- **Score 13+ (needs work):** Present findings and proceed to step 2.

**Override:** If the user explicitly requests changes (e.g., "improve," "fix," "update," "rewrite"), skip the exit gate and proceed to step 2 regardless of score. Present findings first, then propose.

### 2. Decide: Patch or Refactor

This is the critical decision. Not every AGENTS.md needs a rewrite.

**Patch** when the file:

- Already has clear section headers
- Is under 200 lines
- Has mostly specific, actionable instructions
- Just needs gaps filled (missing sections, incomplete rules)

A patch preserves the existing structure and voice. Add what's missing, tighten what's vague, remove what contradicts — but don't reorganize a file that's already organized.

**Refactor** when the file:

- Exceeds 200 lines
- Lacks section headers or has inconsistent structure
- Contains mostly vague or unverifiable instructions
- Has significant contradictions or scope mixing
- Would require so many patches that the result would feel Frankenstein'd

A refactor rewrites the file from scratch, preserving the _intent_ of existing instructions while restructuring them into a well-organized format.

### 3. Present the Plan

Always show the user what you intend to do before making changes:

- Whether you're patching or refactoring, and why
- Which sections you'll add, modify, or remove
- For patches: the specific gaps you identified
- For refactors: the proposed new structure with section headers

Wait for approval before writing.

### 4. Write the Instructions

Apply the patterns from `references/BEST_PRACTICES.md`. The output is always a single AGENTS.md file. Key principles while writing:

- Every instruction should be something an agent can act on or verify
- Group related rules under descriptive headers
- Front-load the most important instructions — agents weight earlier content more heavily
- Use the imperative form ("Use X", "Run Y") not descriptive ("We use X", "Y is preferred")
- Explain _why_ when the reason isn't obvious — agents follow instructions better when they understand the motivation

### 5. Validate

After writing, check the result against the assessment dimensions from step 1. Confirm:

- Under 200 lines (ideally under 100), or uses `@imports` to stay modular
- No contradictions
- No vague instructions that survived the edit
- No scope mixing
- No instructions that duplicate what linters/formatters already enforce
- Every line passes the conciseness test — if removing it wouldn't cause mistakes, cut it
- CLAUDE.md and GEMINI.md symlinks point to AGENTS.md (step 6)

### 6. Set Up Symlinks — DO NOT SKIP THIS STEP

Every run of this skill must end with symlinks in place. The output is always `AGENTS.md`, and both `CLAUDE.md` and `GEMINI.md` must be symlinks pointing to it. This is what makes the single-source-of-truth model work — without symlinks, one platform silently stops reading the instructions.

**If CLAUDE.md or GEMINI.md already exist as symlinks:** Confirm they point to AGENTS.md. Report this to the user ("symlinks already in place").

**If they don't exist:** Create them:

```bash
ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md GEMINI.md
```

**If they exist as regular files (not symlinks):** STOP and warn the user before replacing them. They may contain platform-specific content that needs to be merged into AGENTS.md first. Show the user what would be lost, get approval, then replace with symlinks.

**If the user asked for a "CLAUDE.md" or "GEMINI.md":** Still create AGENTS.md as the source and symlink the requested name to it.

## What This Skill Does NOT Do

- It doesn't create `.claude/rules/` files or platform-specific configuration — those are separate concerns
- It doesn't manage `settings.json` for either platform
- It doesn't handle auto-memory configuration
- It doesn't split a single AGENTS.md into separate CLAUDE.md and GEMINI.md — the whole point is one file, symlinked

## Common Scenarios

**"I don't have an AGENTS.md yet"**
Run the bundled discovery script first: `${CLAUDE_SKILL_DIR}/scripts/discover.sh <project-root>`. It detects the stack, commands, directory structure, and existing agent files — no AI tokens spent on exploration. Present the discovery summary to the user, then draft an AGENTS.md based on it. Only ask about things the script can't discover — like workflow preferences, deployment targets, or team conventions that aren't encoded in config files.

**"My AGENTS.md is too long"**
Audit for redundancy, vague instructions that can be cut, and sections that belong in `@imported` reference files rather than the main body. The main AGENTS.md should be an index of high-signal instructions, not an encyclopedia.

**"Agents keep ignoring my instructions"**
Three common causes: (1) the file is too long and instructions are getting lost in the noise — prune aggressively, (2) the instructions are too vague to act on — rewrite until objectively verifiable, (3) style rules that should be enforced by a linter, not an agent. If the agent does something wrong despite a rule against it, the file is probably too long and the rule is getting lost.

**"I want to add rules for a new project/area"**
Run the full assessment first. If the file is already in good shape, slot the new rules into the existing structure. If adding them reveals deeper issues (the file is already at capacity, the structure doesn't accommodate the new area cleanly), the assessment will surface that and may recommend a refactor instead.

登录后下载/点赞/收藏 ❤ 12 | ★ 0

agents-md

目录结构

SKILL.md

举报内容

提示