学习

数据 社区

技能解读

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

1.从零开始的新技能

触发:“为X创建技能”。深入询问用户,遵循他们的指导。使用下面的结构+规则进行构建。

2. 对话摘录

触发:“学习我们所做的事情的技能”,“捕获这个”,“从上面提取技能”。扫描 - 收集:决策 + 基本原理、约束、工作模式、工作流程、问题、非显而易见的领域事实 过滤 - 只保留非显而易见的、项目特定的知识。削减特工已经知道的内容。范围 - 工作空间技能 (.stagewise/skills/) 如果内容使用特定路径/工具;用户技能(.agents/skills/)如果可广泛重用

3.更新现有技能

触发因素:用户更正了代理行为、推翻了指导、技能错误/过时。在接触任何内容之前先阅读完整的技能替换 - 覆盖错误的内容。切勿附加“注意:以上内容已过时”删除冗余内容。每一句话都赢得了它的位置。保留仍然准确的内容

每次手术后

输出紧凑摘要: 创建 — 路径 + 一行描述 更新 — 路径 + 项目符号:添加/替换/删除 排除 — 被删除的内容 + 为什么(仅提取)

技能结构

Frontmatter(必需):没有 frontmatter 重复。正文不得重述description。 Frontmatter = 发现简介。主体 = 触发器、步骤、约束。参考部分 - 如果存在任何参考文件,则需要:列出每个文件:它包含的内容 + 何时加载它。不公开 = 对代理不可见。

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

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

作者说明文件(原文) SKILL.md

# Learn: write skills

## Workflows

### 1. New skill from scratch

Trigger: "create a skill for X". Ask user intensively, follow their guidance. Build using structure + rules below.

### 2. Extract from conversation

Trigger: "learn-skill for what we did", "capture this", "extract a skill from above".

1. **Scan** — collect: decisions + rationale, constraints, working patterns, workflows, gotchas, non-obvious domain facts
2. **Filter** — keep only non-obvious, project-specific knowledge. Cut what agent already knows.
3. **Scope** — workspace skill (`.stagewise/skills/`) if content uses specific paths/tooling; user skill (`.agents/skills/`) if broadly reusable
4. **Write** — structure into files using rules below, write to path

→ Load `references/session-extraction.md` for full checklist + signal/noise examples.

### 3. Update existing skill

Trigger: user corrected agent behavior, overrode guidance, skill is wrong/outdated.

1. **Read** full skill before touching anything
2. **Replace** — overwrite wrong content. Never append "Note: above is outdated"
3. **Remove** redundancies. Every sentence earns its place.
4. **Preserve** what's still accurate

→ Load `references/skill-updating.md` for full checklist.

---

## After every operation

Output compact summary:
- **Created** — path + one-line description
- **Updated** — path + bullets: added / replaced / removed
- **Excluded** — what was cut + why (extractions only)

---

## Skill structure

```text
skill-name/
├── SKILL.md           required, target <200 lines
├── references/        optional, on-demand
│   └── *.md
├── scripts/           optional, executable scripts
└── assets/            optional, output files (templates, icons, etc.)
```

**Frontmatter (required):**
```yaml
---
name: skill-name
description: What it does + when to use it. Specific — drives discovery.
---
```

**No frontmatter duplication.** Body must not restate `description`. Frontmatter = discovery blurb. Body = triggers, steps, constraints.

**References section — required if any reference files exist:**
List every file: what it contains + *when to load it*. Unlisted = invisible to agent.

```markdown
## References
- `references/render-loops-debugging.md` — workflow for diagnosing excess re-renders. Load when investigating render performance.
```

---

## Authoring rules

### SKILL.md vs. references

**SKILL.md** → everything needed for the typical case: triggers, core steps, universal constraints.

**References** → content needed only *sometimes*:
- Workflow-specific detail (e.g. extraction checklist, update checklist)
- Examples — illustrative, not required to act
- Rules that apply only in certain cases
- Deep guidance for uncommon situations

**Never put universal rules in references.** Always-applies rule → SKILL.md. Agent might skip references.

**The test:** agent handle common case from SKILL.md alone (or + 1 reference max)? No → split is wrong. Fold needed content back into SKILL.md.

### Writing style — caveman speak

Write dense. Drop articles, filler, throat-clearing. Fragments OK. Use `→`, `=`, `+` as connectors. **Bold** key terms. Keep all technical content.

| ❌ Fluffy | ✅ Caveman |
|---|---|
| "You should make sure to always read the file before editing" | "Read before edit. Always." |
| "This step is important because it ensures that..." | "→ prevents X" |
| "I'd recommend using useMemo to memoize the object" | "Wrap in useMemo." |

Rules:
- Imperative/verb-first: "Do X" not "You should do X"
- No meta phrasing: never "this skill tells you to…"
- One term per concept — never synonyms
- Every sentence must add info agent doesn't already have. Cut the rest.

### Progressive disclosure

- **SKILL.md** → target <200 lines. Up to ~500 acceptable; split when approaching limit.
- **Reference files** → also target <200 lines each.
- **One level deep** — references link from SKILL.md only. No ref → ref chains.

### Degrees of freedom

Match specificity to task fragility:
- **High** (prose): multiple valid approaches, context-dependent
- **Medium** (pseudocode/parameterized): preferred pattern exists, variation OK
- **Low** (exact script): fragile or order-sensitive

---

## References

- `references/session-extraction.md` — extraction checklist, signal/noise examples, scope decisions. Load for workflow 2.
- `references/skill-updating.md` — update checklist: conflicts, redundancy, deprecated content. Load for workflow 3.
- `references/workflow-patterns.md` — how to document per-process workflows (steps, primitives, examples). Load when skill needs to document multiple distinct processes.
- `references/authoring-guide.md` — naming, descriptions, content guidelines, anti-patterns, quality checklist. Load for comprehensive authoring guidance.

讨论

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