创作技巧
- 作者仓库星标 0
- 作者仓库 dotagents
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @bastienlimbour · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
编辑前确定路径: 创建技能:运行完整的工作流程。更新技能:检查现有技能并仅编辑请求更改所需的部分。提高目标模糊的技能:首先进行审核,然后修复最高价值的差距。审核技能:首先报告结果,然后停止,除非用户要求编辑。
检查现有技能文件、源材料、真实工作流程、示例、以前的失败以及可用的相邻技能。仅当缺少信息会严重改变技能时,一次提出一个有针对性的问题。对于实质性的新技能或主要重写,请总结预期的文件并要求继续,除非用户已经批准了该确切的工作。
确定可重复的工作、用户、输入、输出、约束、非目标、成功标准以及不应触发技能的未遂任务。比起广泛的工具箱,更喜欢一项连贯的工作。如果建议的技能涵盖不相关的工作,请将其拆分或缩小第一个版本的范围。
阅读 discovery-and-descriptions.md。选择与目录匹配的便携式小写连字符`name`。编写一个`description`,说明该技能的作用以及何时使用它。仅当可以防止可能的误报时,才加载核心触发术语并包含排除项。
阅读spec-and-struct.md 以获取所需的格式。仅从`SKILL.md`开始。仅当捆绑文件获得保留时才添加它们。需要 · 默认操作 每次运行的核心指令 · 保留在 `SKILL.md` 稀有、长或有条件的细节 · 移至 `references/`
阅读内容模式.md。为代理编写操作说明,而不是为人类编写解释性文档。使用适合技能的可扫描结构,而不是复制固定模板。用 `Overview` 1-2 句话来说明该技能的作用及其重要性。让`When To Use`专注于激活指导。仅当阶段标题、表格、示例、危险信号、合理化或验证能够改善行为时才使用它们。
阅读评估.md。每个创作或材料更新都必须包含一个轻量级评估计划或不需要评估的明确原因。添加完整的评估文件,以了解重要的技能、有风险的工作流程、脚本、复杂的激活边界或未来的重复使用。
阅读audit-checklist.md。修复检查表失败的问题并重新检查,直到技能有效、重点突出且可用。如果仅进行审核,则返回按严重程度排序的结果以及具体修复。
# Authoring Skills
## Overview
Create, update, improve, and audit portable Agent Skills. The goal is to make agents reliably better at a repeatable job without bloating context or forcing unnecessary structure.
## When To Use
- Creating a new Agent Skill or `SKILL.md`
- Updating, refactoring, or improving an existing skill
- Designing a skill's name, description, trigger surface, or exclusions
- Organizing bundled skill files such as `references/`, `assets/`, `scripts/`, or `evals/`
- Auditing a skill for structure, discovery, progressive disclosure, scripts, security, or eval coverage
**When NOT to use:**
- Standalone prompts that are not being packaged as Agent Skills
- `AGENTS.md`, hooks, MCP setup, app config, or other non-skill agent configuration
- General documentation, READMEs, or writing tasks unrelated to skill authoring
If the user explicitly wants one of these artifacts packaged as a skill, use this skill for the packaging work.
## Core Principle
Write the simplest and smallest skill that does the job. Add structure, examples, references, assets, scripts, or evals only when they improve the output quality or make the skill easier to discover, follow, verify, or maintain.
## Workflow
For non-trivial work, track your progress with a checklist.
### Phase 1 - Classify
Determine the path before editing:
- Creating a skill: run the full workflow.
- Updating a skill: inspect the existing skill and edit only the parts needed for the requested change.
- Improving a skill with vague goals: audit first, then fix the highest-value gaps.
- Auditing a skill: report findings first and stop unless the user asks for edits.
### Phase 2 - Gather Evidence
Inspect existing skill files, source material, real workflows, examples, previous failures, and adjacent skills when available.
Ask one targeted question at a time only when missing information would materially change the skill. For substantial new skills or major rewrites, summarize the intended files and ask to proceed unless the user already approved that exact work.
### Phase 3 - Define The Boundary
Identify the repeatable job, users, inputs, outputs, constraints, non-goals, success criteria, and near-miss tasks that should not trigger the skill.
Prefer one coherent job over a broad toolbox. If the proposed skill covers unrelated jobs, split it or narrow the first version.
### Phase 4 - Design Discovery
Read [discovery-and-descriptions.md](references/discovery-and-descriptions.md).
Choose a portable lowercase hyphenated `name` that matches the directory. Write a `description` that states what the skill does and when to use it. Front-load core trigger terms and include exclusions only when they prevent likely false positives.
### Phase 5 - Shape The Package
Read [spec-and-structure.md](references/spec-and-structure.md) for required format.
Start with only `SKILL.md`. Add bundled files only when they earn their keep.
| Need | Default action |
| --- | --- |
| Core instructions every run | Keep in `SKILL.md` |
| Rare, long, or conditional detail | Move to `references/` |
| Static templates, sample files, schemas, or images | Put in `assets/` |
| Deterministic, repeated, fragile, or machine-verifiable work | Consider `scripts/` after risk review |
| Non-trivial activation or output quality | Add `evals/` or a lightweight eval plan |
Use minimal frontmatter by default: `name` and `description`. Add optional fields only for concrete compatibility, licensing, metadata, or tool needs.
### Phase 6 - Write The Body
Read [content-patterns.md](references/content-patterns.md).
Write operational instructions for the agent, not explanatory documentation for humans. Use a scannable structure that fits the skill instead of copying a fixed template.
Keep `Overview` to 1-2 sentences about what the skill does and why it matters. Keep `When To Use` focused on activation guidance. Use phase headings, tables, examples, red flags, rationalizations, or verification only when they improve behavior.
### Phase 7 - Evaluate
Read [evaluation.md](references/evaluation.md).
Every creation or material update must include a lightweight eval plan or a clear reason evals are unnecessary. Add full eval files for non-trivial skills, risky workflows, scripts, complex activation boundaries, or repeated future use.
### Phase 8 - Review
Read [audit-checklist.md](references/audit-checklist.md).
Fix checklist failures and re-check until the skill is valid, focused, and usable. If auditing only, return findings ordered by severity with concrete fixes.
## Reference Map
Load only the reference needed for the current decision:
- Skill format and frontmatter: [spec-and-structure.md](references/spec-and-structure.md)
- Names, triggers, and descriptions: [discovery-and-descriptions.md](references/discovery-and-descriptions.md)
- Body organization and progressive disclosure: [content-patterns.md](references/content-patterns.md)
- Evals and iteration: [evaluation.md](references/evaluation.md)
- Scripts, dependencies, and security: [scripts-and-security.md](references/scripts-and-security.md)
- Final review or audits: [audit-checklist.md](references/audit-checklist.md)
Do not preload all references.
## Defaults
- Author portable Agent Skills first. When a local choice is needed, prefer Opencode-compatible `.agents/skills` conventions.
- Keep changes minimal. Do not add backward-compatibility or migration logic without persisted data, external consumers, shipped behavior, or explicit user need.
- Prefer concrete examples and gotchas over generic best-practice prose.
- Use forward-slash relative paths from the skill root.
- Avoid time-sensitive claims unless they are isolated as legacy context.
## Common Rationalizations
| Rationalization | Reality |
| --- | --- |
| "This skill should include every best practice." | Skills should include only guidance that changes agent behavior for the target job. |
| "A fixed template will keep skills consistent." | Consistency helps, but unnecessary sections create noise. Choose sections by need. |
| "Evals are optional polish." | Every material skill change needs at least a lightweight eval plan or an explicit reason evals are unnecessary. |
| "A script would make this look more capable." | Scripts add maintenance and security risk. Add them only when they improve reliability. |
## Red Flags
- The description says "helps with" but does not name concrete triggers.
- The skill tries to cover multiple unrelated jobs.
- References exist but `SKILL.md` does not say when to load them.
- Scripts are present without a clear interface, dependency story, or risk check.
- A non-trivial skill has no eval plan.
## Output
For creation or update tasks, return the files changed, the key design choices, and the eval or validation performed. For audits, return findings first, then suggested fixes. Keep summaries concise.
## Verification
Before finalizing a created or modified skill, confirm:
- [ ] `Overview` explains what the skill does in 1-2 sentences.
- [ ] `When To Use` focuses on activation guidance and near-miss exclusions.
- [ ] The structure is scannable and adaptive, not a forced template.
- [ ] The description is specific enough to trigger correctly among many skills.
- [ ] Bundled files are justified and referenced with load conditions.
- [ ] Scripts, network access, or third-party content received a risk check when present.
- [ ] Evals are included or the reason they are unnecessary is explicit.
按说明文件中的顺序排列。
概述
何时使用
核心原则
工作流程
第一阶段 - 分类
文件/命令 -> references/ · assets/ · scripts/ · evals/ · AGENTS.md · name · description · Overview
内容校验值 -> 0be7873377b9
当前原文的自动摘译,尚未人工审校。
概述
创建、更新、改进和审核便携式代理技能。目标是让智能体可靠地更好地完成可重复的工作,而不需要臃肿的上下文或强制不必要的结构。
何时使用
创建新的代理技能或
SKILL.md更新、重构或改进现有技能 设计技能的名称、描述、触发面或排除 组织捆绑技能文件,例如references/、assets/、scripts/或evals/审核技能的结构、发现、渐进披露、脚本、安全或评估覆盖范围核心原则
写出完成这项工作的最简单、最小的技能。仅当结构、示例、参考、资产、脚本或评估能够提高输出质量或使技能更易于发现、遵循、验证或维护时才添加它们。
工作流程
对于重要的工作,请使用清单跟踪您的进度。