学习
- 作者仓库星标 6,677
- 作者仓库 stagewise
- 领域
- 数据
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @stagewise-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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.
章节与文件索引
按说明文件中的顺序排列。
1.从零开始的新技能
2. 对话摘录
3.更新现有技能
每次手术后
技能结构
文件/命令 -> .stagewise/skills/ · .agents/skills/ · references/session-extraction.md · references/skill-updating.md · description · references/render-loops-debugging.md · references/workflow-patterns.md · references/authoring-guide.md
内容校验值 -> 7084dd6589d3
当前原文的自动摘译,尚未人工审校。
1.从零开始的新技能
触发:“为X创建技能”。深入询问用户,遵循他们的指导。使用下面的结构+规则进行构建。
2. 对话摘录
触发:“学习我们所做的事情的技能”,“捕获这个”,“从上面提取技能”。扫描 - 收集:决策 + 基本原理、约束、工作模式、工作流程、问题、非显而易见的领域事实 过滤 - 只保留非显而易见的、项目特定的知识。削减特工已经知道的内容。范围 - 工作空间技能 (
.stagewise/skills/) 如果内容使用特定路径/工具;用户技能(.agents/skills/)如果可广泛重用3.更新现有技能
触发因素:用户更正了代理行为、推翻了指导、技能错误/过时。在接触任何内容之前先阅读完整的技能替换 - 覆盖错误的内容。切勿附加“注意:以上内容已过时”删除冗余内容。每一句话都赢得了它的位置。保留仍然准确的内容
每次手术后
输出紧凑摘要: 创建 — 路径 + 一行描述 更新 — 路径 + 项目符号:添加/替换/删除 排除 — 被删除的内容 + 为什么(仅提取)
技能结构
Frontmatter(必需):没有 frontmatter 重复。正文不得重述
description。 Frontmatter = 发现简介。主体 = 触发器、步骤、约束。参考部分 - 如果存在任何参考文件,则需要:列出每个文件:它包含的内容 + 何时加载它。不公开 = 对代理不可见。