ln-014-agent-instructions-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: All file refs relative to skills repo root.

路径： 所有文件引用均相对于技能仓库根目录。

Agent Instructions Manager

Agent 指令管理器

Type: L3 Worker Category: 0XX Shared

Creates missing instruction files and audits all (CLAUDE.md, AGENTS.md, GEMINI.md) for quality, consistency, and best practices.

类型： L3 工作组件 分类： 0XX 共享组件

创建缺失的指令文件，并审核所有指令文件（CLAUDE.md、AGENTS.md、GEMINI.md）的质量、一致性与最佳实践。

When to Use

使用场景

After editing any instruction file
After adding/removing MCP servers or hooks
Before release or publishing
When sessions degrade (context bloat symptoms)
First-time project setup (instruction files missing)

编辑任意指令文件后
添加/移除 MCP 服务器或钩子后
发布版本前
会话性能下降时（出现上下文膨胀症状）
首次项目搭建时（指令文件缺失）

Phase 1: Discover Files

阶段1：发现文件

Locate instruction files in target project:

Agent	Primary	Fallback
Claude	`CLAUDE.md`	`.claude/settings.local.json`
Codex	`AGENTS.md`	`.codex/instructions.md`
Gemini	`GEMINI.md`	`AGENTS.md` (shared with Codex)

Report: which files exist (

found

missing

), which agents share files.

定位目标项目中的指令文件：

Agent	主文件	备用文件
Claude	`CLAUDE.md`	`.claude/settings.local.json`
Codex	`AGENTS.md`	`.codex/instructions.md`
Gemini	`GEMINI.md`	`AGENTS.md` （与Codex共享）

报告：哪些文件存在（

已找到

缺失

），哪些Agent共享文件。

Phase 1b: Plugin Conflict Check

阶段1b：插件冲突检查

Skip condition: No

enabledPlugins

in settings OR all plugins are

@levnikolaevich-skills-marketplace

Read
```
~/.claude/settings.json
```
→ parse
```
enabledPlugins
```
Filter: enabled=true AND publisher ≠
```
levnikolaevich-skills-marketplace
```
For each external plugin:
- Locate cache:
```
~/.claude/plugins/cache/{publisher}/{plugin}/*/skills/*/SKILL.md
```
- Read each skill description (frontmatter
```
description:
```
  field)
- Match against conflict signal keywords:

Signal	Keywords in description	Overlap with
Orchestration	"orchestrat", "pipeline", "end-to-end", "lifecycle"	ln-1000 pipeline
Planning	"plan.implement", "brainstorm", "design.spec"	ln-300 task coordinator
Execution	"execut.plan", "subagent.task", "task-by-task"	ln-400/ln-401 executors
Code review	"code.review.dispatch", "review.quality.*spec"	ln-402/ln-310
Quality gate	"quality.gate", "verification.complet", "test-driven.*always"	ln-500 quality gate
Debugging	"systematic.debug", "root.cause.*phase"	problem_solving.md
Git isolation	"worktree.creat", "git.isolat"	git_worktree_fallback.md

Check for
```
hooks/session-start
```
directory (competing SessionStart injection)

Score: 2+ signal categories → CONFLICT. 1 → WARN. 0 → safe

CONFLICT:

"CONFLICT: {plugin} overlaps with ln-* pipeline ({signals}). Disable?"

→ AskUserQuestion → if yes, set to

false

in settings.json

WARN: report, continue

跳过条件： 设置中无

enabledPlugins

或所有插件均来自

@levnikolaevich-skills-marketplace

。

读取
```
~/.claude/settings.json
```
→ 解析
```
enabledPlugins
```
筛选：enabled=true 且发布者≠
```
levnikolaevich-skills-marketplace
```
的插件
针对每个外部插件：
- 定位缓存：
```
~/.claude/plugins/cache/{publisher}/{plugin}/*/skills/*/SKILL.md
```
- 读取每个技能的描述（前置元数据
```
description:
```
  字段）
- 匹配冲突信号关键词：

信号类型	描述中的关键词	冲突对象
编排类	"orchestrat", "pipeline", "end-to-end", "lifecycle"	ln-1000 流水线
规划类	"plan.implement", "brainstorm", "design.spec"	ln-300 任务协调器
执行类	"execut.plan", "subagent.task", "task-by-task"	ln-400/ln-401 执行器
代码评审类	"code.review.dispatch", "review.quality.*spec"	ln-402/ln-310
质量门禁类	"quality.gate", "verification.complet", "test-driven.*always"	ln-500 质量门禁
调试类	"systematic.debug", "root.cause.*phase"	problem_solving.md
Git隔离类	"worktree.creat", "git.isolat"	git_worktree_fallback.md

检查是否存在
```
hooks/session-start
```
目录（存在竞争的SessionStart注入）

评分：≥2个信号类别 → 冲突。1个 → 警告。0个 → 安全

冲突处理：

"冲突：{plugin} 与 ln-* 流水线存在重叠（涉及信号：{signals}）。是否禁用？"

→ 询问用户 → 若确认，在settings.json中设为

false

警告处理：仅报告，继续执行

Phase 2: Create Missing Files

阶段2：创建缺失文件

Skip condition: All files exist OR

dry_run == true

(report what would be created).

跳过条件： 所有文件已存在或

dry_run == true

（仅报告将创建的文件）。

Step 2a: Detect Project Context

步骤2a：检测项目上下文

Field	Source	Fallback
PROJECT_NAME	`package.json` → `name`	`basename(cwd)`
PROJECT_DESCRIPTION	`package.json` → `description`	`[TBD: Project description]`
DATE	current date (YYYY-MM-DD)	—

字段	来源	备用值
PROJECT_NAME	`package.json` → `name`	`basename(cwd)`
PROJECT_DESCRIPTION	`package.json` → `description`	`[待补充：项目描述]`
DATE	当前日期（YYYY-MM-DD）	—

Step 2b: Create CLAUDE.md (if missing)

步骤2b：创建缺失的CLAUDE.md

MANDATORY READ: Load

skills/ln-111-root-docs-creator/references/templates/claude_md_template.md

Replace

{{PROJECT_NAME}}

{{PROJECT_DESCRIPTION}}

{{DATE}}

Mark remaining
```
{{...}}
```
as
```
[TBD: placeholder_name]
```
Write to target project root

必须读取： 加载

skills/ln-111-root-docs-creator/references/templates/claude_md_template.md

替换

{{PROJECT_NAME}}

、

{{PROJECT_DESCRIPTION}}

、

{{DATE}}

将剩余的
```
{{...}}
```
标记为
```
[待补充：placeholder_name]
```
写入目标项目根目录

Step 2c: Create AGENTS.md (if missing)

步骤2c：创建缺失的AGENTS.md

Source: target project's CLAUDE.md (just created or pre-existing).


# AGENTS.md
Detailed guides in \
Codex
AGENTS.md →
| **Code Comments 15-20%** | Writing code | WHY not WHAT. No historical notes. Task/ADR IDs as spec refs only |

#	Transformation	Find	Replace
1	Title	First H1 line	`# AGENTS.md`
2	SCOPE	`Guides in \` docs/``	`Detailed guides in \` docs/`. Skill workflows in individual `SKILL.md` files. Public documentation in `README.md`.`
3	Agent name	`Claude Code` / `Claude` in intro line	`Codex`
4	DAG entry	`CLAUDE.md →`	`AGENTS.md →`
5	Add rule	After last Critical Rules row	Add: `\| Code Comments 15-20% \| Writing code \| WHY not WHAT. No historical notes. Task/ADR IDs as spec refs only \|`

来源：目标项目的CLAUDE.md（刚创建或已存在）。

序号	转换操作	查找内容	替换内容
1	标题	首个H1行	`# AGENTS.md`
2	范围	`Guides in \` docs/``	`详细指南位于\` docs/`。技能工作流位于独立的`SKILL.md`文件。公开文档位于`README.md`。`
3	Agent名称	介绍行中的 `Claude Code` / `Claude`	`Codex`
4	DAG条目	`CLAUDE.md →`	`AGENTS.md →`
5	添加规则	最后一行关键规则后	添加： `\| 代码注释占比15-20% \| 编写代码时 \| 说明原因而非内容。不包含历史记录。仅将任务/ADR ID作为规范引用 \|`

Step 2d: Create GEMINI.md (if missing)

步骤2d：创建缺失的GEMINI.md

Source: target project's AGENTS.md (just created or pre-existing).


# GEMINI.md
Gemini CLI
GEMINI.md →
during context compression:
Code Comments

#	Transformation	Find	Replace
1	Title	First H1 line	`# GEMINI.md`
2	Agent name	`Codex` in intro line	`Gemini CLI`
3	DAG entry	`AGENTS.md →`	`GEMINI.md →`
4	Compact	`during /compact:`	`during context compression:`
5	Remove rule	`Code Comments` row	Delete row

来源：目标项目的AGENTS.md（刚创建或已存在）。


# GEMINI.md
Gemini CLI
GEMINI.md →
during context compression:
代码注释

序号	转换操作	查找内容	替换内容
1	标题	首个H1行	`# GEMINI.md`
2	Agent名称	介绍行中的 `Codex`	`Gemini CLI`
3	DAG条目	`AGENTS.md →`	`GEMINI.md →`
4	术语替换	`during /compact:`	`during context compression:`
5	移除规则	`代码注释` 行	删除该行

Step 2e: Report Creations

步骤2e：报告创建结果

List each created file with its source (template / derived from CLAUDE.md / derived from AGENTS.md).

列出每个已创建的文件及其来源（模板 / 基于CLAUDE.md生成 / 基于AGENTS.md生成）。

Phase 3: Token Budget Audit

阶段3：令牌预算审核

For each instruction file:

Check	Pass	Warn	Fail
Line count	≤100 lines	101-150 lines	>150 lines
Estimated tokens	≤2,500 tokens	2,501-3,500	>3,500
Sections count	≤8 sections	9-12	>12

Token estimation:

wc -w {file}

× 1.3 (English average tokens/word ratio).

Report table per file with line count, word count, estimated tokens.

针对每个指令文件执行以下检查：

检查项	通过	警告	失败
行数	≤100行	101-150行	>150行
预估令牌数	≤2500令牌	2501-3500令牌	>3500令牌
章节数	≤8个章节	9-12个章节	>12个章节

令牌估算公式：

wc -w {file}

× 1.3（英文平均词令牌比）。

按文件生成报告表格，包含行数、词数、预估令牌数。

Phase 4: Prompt Cache Safety

阶段4：提示词缓存安全性检查

Check each file for content that breaks prefix-based prompt caching:

#	Check	Pattern	Severity
1	No timestamps	`grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}'`	WARN
2	No dates in content	`grep -E '(January	February
3	No dynamic counts	`grep -E '\d+ skills\|\d+ tools\|\d+ servers'` (hardcoded counts change)	WARN
4	No absolute paths	`grep -E '[A-Z]:\	/home/
5	Stable structure	No conditional sections ( `if X then include Y` )	INFO

检查每个文件中是否存在破坏前缀式提示词缓存的内容：

序号	检查项	匹配模式	严重程度
1	无时间戳	`grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}'`	警告
2	内容中无日期	`grep -E '(January	February
3	无动态计数	`grep -E '\d+ skills\|\d+ tools\|\d+ servers'` （硬编码计数会变化）	警告
4	无绝对路径	`grep -E '[A-Z]:\	/home/
5	结构稳定	无条件章节（ `if X then include Y` ）	信息

Phase 5: Content Quality

阶段5：内容质量检查

#	Check	Pass	Fail
1	Has build/test commands	Found `npm\|cargo\|pytest\|dotnet` commands	Missing — add essential commands
2	No abstract principles	No `"write quality code"` , `"follow best practices"`	Found vague instructions
3	No redundant docs	No API docs, no full architecture description	Found content discoverable from code
4	Has hard boundaries	Found `NEVER\|ALWAYS\|MUST\|DO NOT` rules	Missing explicit prohibitions
5	Compact Instructions section	`## Compact Instructions` present with preservation priorities	Missing — sessions lose decisions on /compact
6	MCP Tool Preferences	Table mapping built-in → MCP tools	Missing — agents use suboptimal tools
7	No tool output examples	No large code blocks or command outputs	Found — bloats every turn

序号	检查项	通过	失败
1	包含构建/测试命令	找到 `npm\|cargo\|pytest\|dotnet` 命令	缺失 — 添加必要命令
2	无抽象原则	无 `"write quality code"` 、 `"follow best practices"` 这类表述	存在模糊指令
3	无冗余文档	无API文档、无完整架构描述	存在可从代码中获取的内容
4	明确边界规则	存在 `NEVER\|ALWAYS\|MUST\|DO NOT` 类规则	缺失明确禁止性规则
5	包含精简指令章节	存在 `## Compact Instructions` 章节及优先级说明	缺失 — 会话在/compact时会丢失决策信息
6	MCP工具偏好设置	包含内置工具与MCP工具的映射表	缺失 — Agent会使用非最优工具
7	无工具输出示例	无大段代码块或命令输出	存在 — 会膨胀每次交互的上下文

Phase 6: Cross-Agent Consistency

阶段6：跨Agent一致性检查

Compare content across all found instruction files:

Check	Pass	Fail
MCP Tool Preferences	Same table in all files	Missing in some files
Critical Rules	Same core rules	Divergent rules
Build/test commands	Same commands	Different or missing
Structural sections	Same section order	Inconsistent structure

Sync action: For each inconsistency, show diff and suggest which file is source of truth (usually CLAUDE.md).

对比所有已找到的指令文件内容：

检查项	通过	失败
MCP工具偏好设置	所有文件中的表格一致	部分文件缺失
核心规则	核心规则一致	规则存在差异
构建/测试命令	命令一致	命令不同或缺失
章节结构	章节顺序一致	结构不一致

同步操作： 针对每个不一致项，显示差异并建议源文件（通常为CLAUDE.md）。

Phase 7: Report

阶段7：生成报告

Agent Instructions Manager:

Created:  (omit section if nothing created)
- CLAUDE.md (from template, context from package.json)
- AGENTS.md (derived from CLAUDE.md)

Audit:
| File       | Lines | ~Tokens | Cache-safe | Quality | Issues |
|------------|-------|---------|------------|---------|--------|
| CLAUDE.md  | 80    | 2,100   | OK         | 6/7     | Missing Compact Instructions |
| AGENTS.md  | 77    | 2,000   | OK         | 7/7     | OK |
| GEMINI.md  | 75    | 1,950   | OK         | 7/7     | OK |

Cross-agent: OK (or N inconsistencies listed)

Recommendations:
1. Run /init (ln-100) for full context-aware CLAUDE.md with project-specific rules
2. Add ## Compact Instructions to CLAUDE.md

Agent Instructions Manager:

已创建文件：（若无创建则省略本节）
- CLAUDE.md（来自模板，上下文取自package.json）
- AGENTS.md（基于CLAUDE.md生成）

审核结果：
| 文件名称 | 行数 | 预估令牌数 | 缓存安全 | 质量评分 | 问题 |
|------------|-------|---------|------------|---------|--------|
| CLAUDE.md  | 80    | 2,100   | 正常         | 6/7     | 缺失Compact Instructions章节 |
| AGENTS.md  | 77    | 2,000   | 正常         | 7/7     | 无 |
| GEMINI.md  | 75    | 1,950   | 正常         | 7/7     | 无 |

跨Agent一致性：正常（或列出N处不一致）

建议：
1. 运行/init（ln-100）生成包含项目特定规则的全上下文CLAUDE.md
2. 为CLAUDE.md添加## Compact Instructions章节