跳到主内容
智客 ZICQ

技能库 智客分类:文档办公 agent-md-refactor

Agent Md Refactor

重构出膨胀的AGENTS.md,CLAUDE.md,或类似的代理指令文件,以遵循渐进披露原则. 将单文文件分为有组织,有链接的文档.

4124 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

重构出膨胀的AGENTS.md,CLAUDE.md,或类似的代理指令文件,以遵循渐进披露原则. 将单文文件分为有组织,有链接的文档.

何时用

官方 description 未单独写出 Use when。按规范,代理会在用户任务与这段 description 的关键词匹配时激活本技能。

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Agent MD Refactor、Triggers、Quick Reference、Process、Phase 1: Find Contradictions、Contradiction Found。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.

Agent MD RefactorTriggersQuick ReferenceProcessPhase 1: Find ContradictionsContradiction FoundPhase 2: Identify the EssentialsPhase 3: Group the RestPhase 4: Create the File StructureProject NameQuick ReferenceDetailed Instructions

· 许可:MIT

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
agent-md-refactor
description
Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
许可
MIT
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「agent-md-refactor」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-5bfa5972193e3e4c-%E4%BB%A3%E7%90%86-Md-%E9%87%8D%E6%9E%84.html
请存为 .cursor/skills/agent-md-refactor/SKILL.md 或 .claude/skills/agent-md-refactor/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/softaworks/agent-toolkit' --list

npx skills add 'https://github.com/softaworks/agent-toolkit' --skill 'agent-md-refactor'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

name: agent-md-refactor description: Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation. license: MIT

Agent MD Refactor

Refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) to follow progressive disclosure principles - keeping essentials at root and organizing the rest into linked, categorized files.


Triggers

Use this skill when:

  • "refactor my AGENTS.md" / "refactor my CLAUDE.md"
  • "split my agent instructions"
  • "organize my CLAUDE.md file"
  • "my AGENTS.md is too long"
  • "progressive disclosure for my instructions"
  • "clean up my agent config"

Quick Reference

| Phase | Action | Output | |-------|--------|--------| | 1. Analyze | Find contradictions | List of conflicts to resolve | | 2. Extract | Identify essentials | Core instructions for root file | | 3. Categorize | Group remaining instructions | Logical categories | | 4. Structure | Create file hierarchy | Root + linked files | | 5. Prune | Flag for deletion | Redundant/vague instructions |


Process

Phase 1: Find Contradictions

Identify any instructions that conflict with each other.

Look for:

  • Contradictory style guidelines (e.g., "use semicolons" vs "no semicolons")
  • Conflicting workflow instructions
  • Incompatible tool preferences
  • Mutually exclusive patterns

For each contradiction found:

## Contradiction Found

**Instruction A:** [quote]
**Instruction B:** [quote]

**Question:** Which should take precedence, or should both be conditional?

Ask the user to resolve before proceeding.


Phase 2: Identify the Essentials

Extract ONLY what belongs in the root agent file. The root should be minimal - information that applies to every single task.

Essential content (keep in root): | Category | Example | |----------|---------| | Project description | One sentence: "A React dashboard for analytics" | | Package manager | Only if not npm (e.g., "Uses pnpm") | | Non-standard commands | Custom build/test/typecheck commands | | Critical overrides | Things that MUST override defaults | | Universal rules | Applies to 100% of tasks |

NOT essential (move to linked files):

  • Language-specific conventions
  • Testing guidelines
  • Code style details
  • Framework patterns
  • Documentation standards
  • Git workflow details

Phase 3: Group the Rest

Organize remaining instructions into logical categories.

Common categories: | Category | Contents | |----------|----------| | typescript.md | TS conventions, type patterns, strict mode rules | | testing.md | Test frameworks, coverage, mocking patterns | | code-style.md | Formatting, naming, comments, structure | | git-workflow.md | Commits, branches, PRs, reviews | | architecture.md | Patterns, folder structure, dependencies | | api-design.md | REST/GraphQL conventions, error handling | | security.md | Auth patterns, input validation, secrets | | performance.md | Optimization rules, caching, lazy loading |

Grouping rules:

  1. Each file should be self-contained for its topic
  2. Aim for 3-8 files (not too granular, not too broad)
  3. Name files clearly: {topic}.md
  4. Include only actionable instructions

Phase 4: Create the File Structure

Output structure:

project-root/
├── CLAUDE.md (or AGENTS.md)     # Minimal root with links
└── .claude/                      # Or docs/agent-instructions/
    ├── typescript.md
    ├── testing.md
    ├── code-style.md
    ├── git-workflow.md
    └── architecture.md

Root file template:

# Project Name

One-sentence description of the project.

## Quick Reference

- **Package Manager:** pnpm
- **Build:** `pnpm build`
- **Test:** `pnpm test`
- **Typecheck:** `pnpm typecheck`

## Detailed Instructions

For specific guidelines, see:
- [TypeScript Conventions](.claude/typescript.md)
- [Testing Guidelines](.claude/testing.md)
- [Code Style](.claude/code-style.md)
- [Git Workflow](.claude/git-workflow.md)
- [Architecture Patterns](.claude/architecture.md)

Each linked file template:

# {Topic} Guidelines

## Overview
Brief context for when these guidelines apply.

## Rules

### Rule Category 1
- Specific, actionable instruction
- Another specific instruction

### Rule Category 2
- Specific, actionable instruction

## Examples

### Good
\`\`\`typescript
// Example of correct pattern
\`\`\`

### Avoid
\`\`\`typescript
// Example of what not to do
\`\`\`

Phase 5: Flag for Deletion

Identify instructions that should be removed entirely.

Delete if: | Criterion | Example | Why Delete | |-----------|---------|------------| | Redundant | "Use TypeScript" (in a .ts project) | Agent already knows | | Too vague | "Write clean code" | Not actionable | | Overly obvious | "Don't introduce bugs" | Wastes context | | Default behavior | "Use descriptive variable names" | Standard practice | | Outdated | References deprecated APIs | No longer applies |

Output format:

## Flagged for Deletion

| Instruction | Reason |
|-------------|--------|
| "Write clean, maintainable code" | Too vague to be actionable |
| "Use TypeScript" | Redundant - project is already TS |
| "Don't commit secrets" | Agent already knows this |
| "Follow best practices" | Meaningless without specifics |

Execution Checklist

[ ] Phase 1: All contradictions identified and resolved
[ ] Phase 2: Root file contains ONLY essentials
[ ] Phase 3: All remaining instructions categorized
[ ] Phase 4: File structure created with proper links
[ ] Phase 5: Redundant/vague instructions removed
[ ] Verify: Each linked file is self-contained
[ ] Verify: Root file is under 50 lines
[ ] Verify: All links work correctly

Anti-Patterns

| Avoid | Why | Instead | |-------|-----|---------| | Keeping everything in root | Bloated, hard to maintain | Split into linked files | | Too many categories | Fragmentation | Consolidate related topics | | Vague instructions | Wastes tokens, no value | Be specific or delete | | Duplicating defaults | Agent already knows | Only override when needed | | Deep nesting | Hard to navigate | Flat structure with links |


Examples

Before (Bloated Root)

# CLAUDE.md

This is a React project.

## Code Style
- Use 2 spaces
- Use semicolons
- Prefer const over let
- Use arrow functions
... (200 more lines)

## Testing
- Use Jest
- Coverage > 80%
... (100 more lines)

## TypeScript
- Enable strict mode
... (150 more lines)

After (Progressive Disclosure)

# CLAUDE.md

React dashboard for real-time analytics visualization.

## Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run tests with coverage
- `pnpm build` - Production build

## Guidelines
- [Code Style](.claude/code-style.md)
- [Testing](.claude/testing.md)
- [TypeScript](.claude/typescript.md)

Verification

After refactoring, verify:

  1. Root file is minimal - Under 50 lines, only universal info
  2. Links work - All referenced files exist
  3. No contradictions - Instructions are consistent
  4. Actionable content - Every instruction is specific
  5. Complete coverage - No instructions were lost (unless flagged for deletion)
  6. Self-contained files - Each linked file stands alone

相关技能

文档办公

Ontology

为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…

文档办公

Nano Pdf

使用纳米-pdf CLI编辑带有自然语言指令的PDF.

文档办公

Word / DOCX

创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…

文档办公

Api Gateway

通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…