Back to Details

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:
AgentPrimaryFallback
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
.
  1. Read 
    ~/.claude/settings.json
    → parse 
    enabledPlugins
  2. Filter: enabled=true AND publisher ≠ 
    levnikolaevich-skills-marketplace
  3. 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:
SignalKeywords in descriptionOverlap 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)
  1. Score: 2+ signal categories → CONFLICT. 1 → WARN. 0 → safe
  2. CONFLICT: 
    "CONFLICT: {plugin} overlaps with ln-* pipeline ({signals}). Disable?"
    → AskUserQuestion → if yes, set to 
    false
    in settings.json
  3. WARN: report, continue
跳过条件： 设置中无
enabledPlugins
或所有插件均来自
@levnikolaevich-skills-marketplace
。
  1. 读取
    ~/.claude/settings.json
    → 解析
    enabledPlugins
  2. 筛选：enabled=true 且 发布者≠
    levnikolaevich-skills-marketplace
    的插件
  3. 针对每个外部插件：
    • 定位缓存：
      ~/.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注入）
  1. 评分：≥2个信号类别 → 冲突。1个 → 警告。0个 → 安全
  2. 冲突处理：
    "冲突：{plugin} 与 ln-* 流水线存在重叠（涉及信号：{signals}）。是否禁用？"
    → 询问用户 → 若确认，在settings.json中设为
    false
  3. 警告处理：仅报告，继续执行

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：检测项目上下文

FieldSourceFallback
PROJECT_NAME
package.json
→ 
name
basename(cwd)
PROJECT_DESCRIPTION
package.json
→ 
description
[TBD: Project description]
DATEcurrent 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

  1. MANDATORY READ: Load 
    skills/ln-111-root-docs-creator/references/templates/claude_md_template.md
  2. Replace 
    {{PROJECT_NAME}}
    , 
    {{PROJECT_DESCRIPTION}}
    , 
    {{DATE}}
  3. Mark remaining 
    {{...}}
    as 
    [TBD: placeholder_name]
  4. Write to target project root
  1. 必须读取： 加载
    skills/ln-111-root-docs-creator/references/templates/claude_md_template.md
  2. 替换
    {{PROJECT_NAME}}
    、
    {{PROJECT_DESCRIPTION}}
    、
    {{DATE}}
  3. 将剩余的
    {{...}}
    标记为
    [待补充：placeholder_name]
  4. 写入目标项目根目录

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

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

Source: target project's CLAUDE.md (just created or pre-existing).
#TransformationFindReplace
1TitleFirst H1 line
# AGENTS.md
2SCOPE
Guides in \
docs/``
Detailed guides in \
docs/`. Skill workflows in individual `SKILL.md` files. Public documentation in `README.md`.`
3Agent name
Claude Code
/ 
Claude
in intro line
Codex
4DAG entry
CLAUDE.md →
AGENTS.md →
5Add ruleAfter last Critical Rules rowAdd: 
| **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`。`
3Agent名称介绍行中的
Claude Code
/ 
Claude
Codex
4DAG条目
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).
#TransformationFindReplace
1TitleFirst H1 line
# GEMINI.md
2Agent name
Codex
in intro line
Gemini CLI
3DAG entry
AGENTS.md →
GEMINI.md →
4Compact
during /compact:
during context compression:
5Remove rule
Code Comments
row		Delete row
来源：目标项目的AGENTS.md（刚创建或已存在）。
序号转换操作查找内容替换内容
1标题首个H1行
# GEMINI.md
2Agent名称介绍行中的
Codex
Gemini CLI
3DAG条目
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:
CheckPassWarnFail
Line count≤100 lines101-150 lines>150 lines
Estimated tokens≤2,500 tokens2,501-3,500>3,500
Sections count≤8 sections9-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:
#CheckPatternSeverity
1No timestamps
grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}'
WARN
2No dates in content`grep -E '(JanuaryFebruary
3No dynamic counts
grep -E '\d+ skills|\d+ tools|\d+ servers'
(hardcoded counts change)		WARN
4No absolute paths`grep -E '[A-Z]:\/home/
5Stable structureNo conditional sections (
if X then include Y
)		INFO
检查每个文件中是否存在破坏前缀式提示词缓存的内容：
序号检查项匹配模式严重程度
1无时间戳
grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}'
警告
2内容中无日期`grep -E '(JanuaryFebruary
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：内容质量检查

#CheckPassFail
1Has build/test commandsFound 
npm|cargo|pytest|dotnet
commands		Missing — add essential commands
2No abstract principlesNo 
"write quality code"
, 
"follow best practices"
Found vague instructions
3No redundant docsNo API docs, no full architecture descriptionFound content discoverable from code
4Has hard boundariesFound 
NEVER|ALWAYS|MUST|DO NOT
rules		Missing explicit prohibitions
5Compact Instructions section
## Compact Instructions
present with preservation priorities		Missing — sessions lose decisions on /compact
6MCP Tool PreferencesTable mapping built-in → MCP toolsMissing — agents use suboptimal tools
7No tool output examplesNo large code blocks or command outputsFound — 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时会丢失决策信息
6MCP工具偏好设置包含内置工具与MCP工具的映射表缺失 — Agent会使用非最优工具
7无工具输出示例无大段代码块或命令输出存在 — 会膨胀每次交互的上下文

Phase 6: Cross-Agent Consistency

阶段6：跨Agent一致性检查

Compare content across all found instruction files:
CheckPassFail
MCP Tool PreferencesSame table in all filesMissing in some files
Critical RulesSame core rulesDivergent rules
Build/test commandsSame commandsDifferent or missing
Structural sectionsSame section orderInconsistent 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章节

Definition of Done

完成标准

  • All instruction files discovered
  • Missing files created (CLAUDE.md from template, AGENTS/GEMINI derived)
  • Token budget within limits (≤2,500 tokens each)
  • No prompt cache breakers found (or reported as WARN)
  • Content quality checks passed (or issues reported)
  • Cross-agent consistency verified
  • Report generated with creation log and actionable recommendations
  • No conflicting external plugins detected (or user confirmed keep)
Version: 2.1.0 Last Updated: 2026-03-24
  • 所有指令文件已被发现
  • 缺失文件已创建（CLAUDE.md来自模板，AGENTS/GEMINI基于已有文件生成）
  • 令牌预算符合限制（每个文件≤2500令牌）
  • 未发现提示词缓存破坏项（或已报告为警告）
  • 内容质量检查通过（或已报告问题）
  • 跨Agent一致性已验证
  • 已生成包含创建日志与可执行建议的报告
  • 未检测到冲突外部插件（或已确认保留冲突插件）
版本： 2.1.0 最后更新： 2026-03-24