技能负载提示

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

失败模式

大型技能通常附带丰富的参考文件 (references/*.md),其中包含承载细节 - 完整的 ARIA 模式、禁用词汇列表、前后示例、原型 - 以及总结它们的 SKILL.md 正文。代理读取主体,感觉它已经“足够了”,并且永远不会散开。参考文件变得沉重。这是内联替代引用反模式。这是组织良好的技能表现不佳的最常见原因。

症状(如何发现)

如果有两个或多个应用,SKILL.md 可能会出现此问题:主体超过 250 行,并且内联清单、表格或也存在于引用文件中的禁用单词列表。 “参考索引”/“文件”部分位于底部,操作循环之后。参考文献以带限制的短语引入:“要了解深度,请阅读 X”、“请参阅 X 了解详细信息”、“X 有更多内容”。没有预先的“路由器”映射任务 → 强制文件。

修复 1 — 在顶部添加所需的读取路由器

在技能的开头段落之后(在任何“操作循环”/“步骤”部分之前)插入一个表格。该表映射了任务类型→该任务必须读取的文件。模板:将路由器与其正下方的参考索引配对:每个文件包含的内容的一行描述,因此路由器告诉代理何时加载,索引告诉代理他们得到什么。

修复 2 — 在操作步骤中使用硬停止指令

具有相应参考文件的每个步骤最后都会有一个强制读取指令。用命令式的措辞代替柔和的措辞。之前:之后: STOP 指令的三个规则: 将“STOP”一词加粗。这是一种视觉中断。

修复 3 — 将重复的内联内容修剪为要点绊线

当 SKILL.md 步骤包含也在参考文件中的 10 项清单时,代理会读取清单并跳过参考。将内联削减为 2-3 行“绊线”——足以让代理在扫描期间检测违规行为,但显然不完整。之前(内联 10 项 WCAG 检查表):之后(3 行绊线 + 强制阅读):积极修剪。如果内联列表和引用覆盖相同的区域,则引用总是获胜。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@pedronauck · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md
# Skill Load Tips

Refactor pattern for SKILL.md files where the body is the only thing the agent ever reads. The references/ folder might as well not exist.

## The Failure Mode

Large skills frequently ship with rich reference files (`references/*.md`) that contain the load-bearing detail — full ARIA patterns, banned-vocab lists, before/after examples, archetypes — and a SKILL.md body that summarizes them. The agent reads the body, feels it has "enough," and never fans out. The reference files become dead weight.

This is the **inline-substitutes-for-reference antipattern**. It is the single most common reason a well-organized skill underperforms.

## Symptoms (how to spot it)

A SKILL.md likely has this problem if **two or more** apply:

- Body is over 250 lines and inlines checklists, tables, or banned-word lists that also live in a referenced file.
- The "Reference Index" / "Files" section is at the bottom, after the operating loop.
- References are introduced with hedged phrases: *"For depth, read X"*, *"see X for details"*, *"X has more"*.
- No upfront "router" mapping task → mandatory file.
- Reference files are linked from other reference files (deep nesting), not directly from SKILL.md.
- Reference files over 100 lines have no table of contents at the top.

## The Four Fixes (apply in order)

### Fix 1 — Add a Required Reading Router at the top

Insert a table immediately after the skill's opening paragraph (before any "Operating Loop" / "Steps" section). The table maps task type → file(s) that **MUST** be read for that task.

**Template:**

```markdown
## Required Reading Router

Match your task to the row. Read the listed files **in full before** producing output. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer, not a substitute.

| Task                                          | MUST read                                                    |
| --------------------------------------------- | ------------------------------------------------------------ |
| [Task type A]                                 | `references/file-a.md`                                       |
| [Task type B]                                 | `references/file-b.md` + `references/file-c.md`              |
| [Task type C]                                 | `references/file-d.md`                                       |
```

Pair the router with a **Reference Index** directly below it: one-line descriptions of *what each file contains*, so the router tells the agent *when* to load and the index tells *what they get*.

### Fix 2 — Use hard STOP directives in operating steps

Every step that has a corresponding reference file gets a forced-read directive at the end. Replace soft phrasing with imperative.

**Before:**
```markdown
For ARIA component patterns and verification recipes, read `references/accessibility-floor.md`.
```

**After:**
```markdown
**STOP. Read `references/accessibility-floor.md` in full before implementing or reviewing any interactive widget.** That file contains the complete ARIA patterns (dialog, combobox, menu, tabs, slider, listbox) and the verification recipes. The inline summary above is a tripwire, not the contract.
```

Three rules for STOP directives:

1. Bold the word **STOP**. It is a visual interrupt.
2. Name the trigger condition ("when implementing an interactive widget", "when extending tokens"). Not just "if you want depth."
3. State that the inline content is a tripwire, not the source of truth.

### Fix 3 — Trim duplicated inline content to gist tripwires

When a SKILL.md step contains a 10-bullet checklist that is also in a reference file, the agent reads the checklist and skips the reference. Cut the inline to a 2-3 line "tripwire" — enough for the agent to detect violations during scanning, but obviously incomplete.

**Before** (inline 10-bullet WCAG checklist):
```markdown
- Text contrast ≥ 4.5:1 (≥ 3:1 for large text)
- Non-text indicators contrast ≥ 3:1
- Focus visible (2px minimum)
- Keyboard reachable
- Target size ≥ 24×24
- prefers-reduced-motion honored
- Semantic landmarks
- Headings in order
- Form controls labeled
- Errors associated via aria-describedby
```

**After** (3-line tripwire + forced read):
```markdown
Gist tripwires — the floor items that catch most slop:

- Text contrast ≥ 4.5:1; focus-visible ≥ 2px on every interactive element.
- Full keyboard reachability; `prefers-reduced-motion` honored.
- Semantic landmarks + heading order; form controls programmatically labeled.

**STOP. Read `references/accessibility-floor.md` in full before implementing or reviewing any interactive widget.** The three bullets above are tripwires, not the contract.
```

Trim aggressively. If the inline list and the reference cover the same ground, the reference always wins.

### Fix 4 — Flatten reference depth to one level

Per Anthropic's docs: when references link to references, the agent uses partial reads (`head -100`) and misses content. All `references/*.md` files must be linked directly from SKILL.md, not from each other.

**Bad:**
```
SKILL.md → references/advanced.md → references/details.md
```

**Good:**
```
SKILL.md → references/advanced.md
SKILL.md → references/details.md
```

Also: any reference file over 100 lines needs a `## Contents` section at the top, so partial reads still surface the scope.

## Anti-Patterns

Things that look like fixes but aren't:

- **Adding "(important)" or emoji to existing trigger lines.** The agent reads tone, not decoration. Mandatory phrasing requires verbs (`STOP. Read…`), not adjectives.
- **Making references shorter so the body can stay inline.** The opposite of the goal. References should grow as the body shrinks.
- **Adding a "TL;DR" at the top of every reference file.** The agent reads the TL;DR and skips the body. Use a Contents TOC instead — names of sections, not summaries.
- **Renaming references to suggest urgency** (`URGENT-read-this.md`, `MUST-READ.md`). The filename does not change the read decision; the trigger phrasing in SKILL.md does.
- **Splitting SKILL.md into many small files at the same level.** SKILL.md is the single entry point. Multiple top-level skill files break discovery.

## Refactor Checklist

Before declaring a refactor done, verify against the rewritten SKILL.md:

- [ ] Required Reading Router exists in the first 50 lines (after intro/philosophy).
- [ ] Reference Index sits next to the Router.
- [ ] Every operating step that has a corresponding reference file ends with a `**STOP. Read references/X.md …**` directive.
- [ ] Inline checklists that duplicate reference content have been trimmed to ≤ 3 bullets, labeled as "tripwires" or "gist."
- [ ] No reference file links to another reference file (one level deep only).
- [ ] Reference files > 100 lines have a `## Contents` TOC at the top.
- [ ] SKILL.md body is under 500 lines (Anthropic's recommended ceiling).
- [ ] No `For depth, see X` or `Read X for more` phrasing remains — every reference mention is either router/index (descriptive) or a STOP directive (mandatory).

## How To Run a Refactor Pass

1. Open SKILL.md and the `references/` directory side by side.
2. Inventory: list every reference file and what it covers.
3. Diagnose: walk the Symptoms list above; mark each hit.
4. Apply Fix 1 (Router + Index), then Fix 2 (STOPs), then Fix 3 (trim inline), then Fix 4 (flatten depth + add TOCs).
5. Run the checklist. If any item is unchecked, the refactor is not done.
6. Test by asking a fresh agent instance to perform a task that requires a reference file. Observe whether it actually reads the file. If it doesn't, the STOP directive for that file is too weak — strengthen the trigger condition.

## When NOT To Use

- Authoring a new skill from scratch — use `skill-best-practices`.
- Editing reference files themselves without touching SKILL.md.
- Skills under 150 lines with no reference files (nothing to route).
- AGENTS.md / CLAUDE.md refactors — those follow different rules; use `agent-md-refactor`.

## Bottom Line

```
A reference file the agent never loads is a reference file that does not exist.
The body of SKILL.md is a dispatcher, not an encyclopedia.
Trim the inline. Force the load. Flatten the depth.
```

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。