技能创作
- 作者仓库星标 196
- 作者仓库 daaf
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @DAAF-Contribution-Community · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Skill Authoring
Guide for creating and auditing DAAF agent skills. Covers SKILL.md format, frontmatter requirements and validation rules, controlled vocabulary for metadata, progressive disclosure patterns, decision trees, reference files, and bundled resource organization. Use when creating a new skill, reviewing or auditing skill structure and frontmatter, or debugging skill loading and triggering issues. For creating agent definition files (.claude/agents/*.md), use agent-authoring instead.
Quick reference for creating well-structured Skills. Use decision trees below to find guidance, then load detailed references as needed.
## What is a Skill?
A Skill is a reusable instruction set that extends agent capabilities:
- **SKILL.md file**: Required entry point with YAML frontmatter + Markdown body
- **Progressive disclosure**: Metadata loaded at startup, body on trigger, resources on-demand
- **Bundled resources**: Optional `scripts/`, `references/`, `assets/` directories
- **On-demand loading**: Agent calls `skill({ name: "skill-name" })` to load
## How to Use This Skill
### Reference File Structure
| File | Purpose | When to Read |
|------|---------|--------------|
| `quickstart.md` | Minimal skill, directory setup | Creating first skill |
| `frontmatter.md` | YAML spec, validation rules, description writing | Writing frontmatter |
| `structure.md` | Body patterns, section templates, content patterns | Organizing content |
| `progressive-disclosure.md` | Three-level loading, splitting | Managing token budget |
| `references-resources.md` | scripts/, references/, assets/ | Adding bundled resources |
| `testing-iteration.md` | Test prompts, iteration workflow, multi-model testing | Validating and improving skills |
| `gotchas.md` | Anti-patterns, validation errors, diagnostics | Debugging or reviewing |
### Reading Order
1. **Creating a skill?** Start with `quickstart.md` then `frontmatter.md`
2. **Structuring content?** Read `structure.md` then `progressive-disclosure.md`
3. **Adding resources?** See `references-resources.md`
4. **Testing and improving?** See `testing-iteration.md`
5. **Having issues?** Check `gotchas.md` first
## Quick Decision Trees
### "I need to create a skill"
```
Creating a new skill?
├─ Where to put it → ./references/quickstart.md
├─ Minimal example → ./references/quickstart.md
├─ Write frontmatter → ./references/frontmatter.md
├─ Name validation → ./references/frontmatter.md
└─ Description best practices → ./references/frontmatter.md
```
### "I need to structure the body"
```
Structuring SKILL.md body?
├─ Workflow-based (sequential steps) → ./references/structure.md
├─ Task-based (tool collection) → ./references/structure.md
├─ Reference-based (standards/specs) → ./references/structure.md
├─ Capabilities-based (features) → ./references/structure.md
├─ Decision tree format → ./references/structure.md
└─ Table conventions → ./references/structure.md
```
### "I need to manage content size"
```
Content too large?
├─ Understand three-level loading → ./references/progressive-disclosure.md
├─ When to split into references → ./references/progressive-disclosure.md
├─ Domain-specific organization → ./references/progressive-disclosure.md
├─ Framework/variant splitting → ./references/progressive-disclosure.md
└─ Token budget guidelines → ./references/progressive-disclosure.md
```
### "I need to add resources"
```
Adding bundled resources?
├─ Executable scripts → ./references/references-resources.md
├─ Documentation files → ./references/references-resources.md
├─ Template assets → ./references/references-resources.md
├─ When to use each type → ./references/references-resources.md
└─ Directory structure → ./references/references-resources.md
```
### "I need to test or improve a skill"
```
Testing or iterating?
├─ Create test prompts → ./references/testing-iteration.md
├─ Test triggering accuracy → ./references/testing-iteration.md
├─ Iterate based on feedback → ./references/testing-iteration.md
├─ Test across models → ./references/testing-iteration.md
└─ Observe navigation patterns → ./references/testing-iteration.md
```
### "Something isn't working"
```
Debugging a skill?
├─ Skill not loading → ./references/gotchas.md
├─ Skill undertriggering → ./references/gotchas.md
├─ Skill overtriggering → ./references/gotchas.md
├─ Validation errors → ./references/gotchas.md
├─ Name format issues → ./references/frontmatter.md
├─ Description too long → ./references/frontmatter.md
└─ Common anti-patterns → ./references/gotchas.md
```
## Quick Reference
### Minimal SKILL.md Template
```yaml
---
name: my-skill-name
description: What this skill does. When to use it (specific triggers).
metadata:
audience: target-users
domain: skill-domain
---
# My Skill Name
Brief intro sentence.
## Section 1
Content here.
```
### Directory Structure
```
.claude/skills/<name>/
├── SKILL.md # Required
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, images
```
### Frontmatter Validation Rules
| Field | Required | Constraints |
|-------|----------|-------------|
| `name` | Yes | Lowercase alphanumeric + hyphens, 1-64 chars, no leading/trailing/consecutive hyphens |
| `description` | Yes | 1-1024 chars, no angle brackets (`<` `>`), include what + when |
| `metadata` | No | Key-value pairs (strings) |
### Name Validation Regex
```
^[a-z0-9]+(-[a-z0-9]+)*$
```
### Content Limits
| Component | Limit | Notes |
|-----------|-------|-------|
| Name | 64 chars | Lowercase hyphen-case |
| Description (frontmatter) | 250 chars | **Hard limit** — truncated at 250 chars in system prompt; all agents see this |
| Description (body) | ~500 chars | Full description as plain paragraph after `# Title`; loaded with skill |
| SKILL.md body | <500 lines | Guideline, not enforced |
| SKILL.md body | <5000 words | Keep concise |
| Metadata per skill | ~100 words | Always in context |
### Core Principles
| Principle | Meaning |
|-----------|---------|
| **Concise is Key (SKILL.md)** | The SKILL.md body shares context with conversation history; justify every token there. Claude is already smart — only add context it doesn't already have |
| **Thorough is Key (references)** | Reference files are loaded on-demand at Level 3. Their token cost is incurred only when needed, so they should be comprehensive — encode all discovered knowledge rather than summarizing. Err on the side of more detail in reference files |
| **Progressive Disclosure** | Load only what's needed, when needed |
| **Appropriate Freedom** | Match specificity to task fragility (high freedom for flexible tasks, low freedom for fragile/critical operations) |
| **Explain the Why** | Use reasoning over rigid directives. If you find yourself writing ALWAYS/NEVER in all caps, reframe and explain the reasoning instead — it's more effective |
| **Examples over Prose** | Show input/output pairs rather than describing behavior in paragraphs |
| **Test and Iterate** | Create test prompts, observe behavior, refine. See `./references/testing-iteration.md` |
### Essential Do's
- Before creating a new skill, read 1-2 existing skills of the same type as structural exemplars (e.g., for data source skills, read an existing data source SKILL.md; for tool skills, read `polars` or `plotnine`)
- Include "what it does" AND "when to use it" in description
- Keep frontmatter description ≤250 chars — this is the ONLY text agents see when deciding whether to load a skill; it gets truncated at 250 chars in the system prompt
- Preserve the full description as a plain paragraph immediately after the `# Title` heading in the body — this provides complete context once the skill is loaded
- Prioritize in the 250-char budget: (1) what it is, (2) key triggers/use cases, (3) disambiguation from similar skills (e.g., "For FE use pyfixest; for GLM use statsmodels")
- Write descriptions in third person ("Processes files" not "I help you process files")
- Make descriptions slightly "pushy" to combat undertriggering
- Front-load important words in description (may be truncated in UI)
- Explain *why* behind instructions, not just *what*
- Use decision trees for navigation
- Keep SKILL.md under 500 lines
- Split large content into `references/` files
- Use tables for quick lookup
- Use consistent terminology throughout (pick one term, stick with it)
- Test skills with realistic prompts before finalizing
- Test scripts before including
- Include metadata references (codebook URLs) for data source skills — see `datasets-reference.md` codebook column
### Essential Don'ts
- Don't include README.md, CHANGELOG.md, or auxiliary docs
- Don't put "When to Use" sections in body (loaded too late)
- Don't duplicate content between SKILL.md and references
- Don't nest references more than one level deep
- Don't use angle brackets in description
- Don't start/end name with hyphens
- Don't use heavy-handed ALWAYS/NEVER/MUST in all caps — explain reasoning instead
- Don't offer too many options — provide a default with an escape hatch
- Don't include time-sensitive information (use "Old patterns" `<details>` sections if needed)
- Don't use Windows-style backslash paths (always forward slashes)
### Skill Registration
Skills are automatically discovered via their YAML frontmatter — the orchestrator sees all skills listed in the system message at conversation start. No manual registration is needed for triggering. Once the skill's `SKILL.md` is placed in `.claude/skills/{skill-name}/`, it becomes available immediately.
**Framework integration beyond discovery:** If the skill should be preloaded by specific agents (via `skills:` frontmatter), referenced in pipeline stage mappings, or wired into workflow documentation, additional registration is required. See `agent_reference/FRAMEWORK_INTEGRATION_CHECKLIST.md` § 1 (items S8-S10) for the complete list of conditional integration points.
## Data Source Skills: Metadata References
When authoring a data source skill, include a codebook reference section if codebooks exist for the source. Follow the existing pattern (modeled after PSEO):
```markdown
### [Source] Codebooks
| Dataset | Codebook Path |
|---------|---------------|
| ... | `path/to/codebook_name` |
> Codebooks are `.xls` files on both mirrors. See `datasets-reference.md` for full catalog
> and `fetch-patterns.md` for `get_codebook_url()`. For human reference — not parsed programmatically.
```
The codebook path comes from the `codebook` column in `datasets-reference.md`. Metadata files are for human reference only — they are not parsed programmatically by the pipeline.
## Topic Index
| Topic | Reference File |
|-------|---------------|
| Directory location | `./references/quickstart.md` |
| Minimal example | `./references/quickstart.md` |
| First skill walkthrough | `./references/quickstart.md` |
| Name field spec | `./references/frontmatter.md` |
| Description field spec | `./references/frontmatter.md` |
| Description writing tips | `./references/frontmatter.md` |
| Optional fields | `./references/frontmatter.md` |
| Validation rules | `./references/frontmatter.md` |
| Body patterns | `./references/structure.md` |
| Decision tree format | `./references/structure.md` |
| Table conventions | `./references/structure.md` |
| Section templates | `./references/structure.md` |
| Content patterns (checklists, feedback loops) | `./references/structure.md` |
| Three-level loading | `./references/progressive-disclosure.md` |
| Content splitting | `./references/progressive-disclosure.md` |
| Token budget | `./references/progressive-disclosure.md` |
| scripts/ directory | `./references/references-resources.md` |
| Script error handling | `./references/references-resources.md` |
| references/ directory | `./references/references-resources.md` |
| assets/ directory | `./references/references-resources.md` |
| Test prompts | `./references/testing-iteration.md` |
| Triggering tests | `./references/testing-iteration.md` |
| Multi-model testing | `./references/testing-iteration.md` |
| Iteration workflow | `./references/testing-iteration.md` |
| Observing skill behavior | `./references/testing-iteration.md` |
| Validation errors | `./references/gotchas.md` |
| Anti-patterns | `./references/gotchas.md` |
| Undertriggering / overtriggering | `./references/gotchas.md` |
| Pre-submission checklist | `./references/gotchas.md` |
章节与文件索引
按说明文件中的顺序排列。
什么是技能?
参考文件结构
阅读顺序
Frontmatter 验证规则
内容限制
文件/命令 -> scripts/ · references/ · assets/ · skill({ name: "skill-name" }) · quickstart.md · frontmatter.md · structure.md · progressive-disclosure.md
内容校验值 -> 489e7347b8a2
当前原文的自动摘译,尚未人工审校。
什么是技能?
Skill 是扩展 Agent 功能的可重用指令集: SKILL.md 文件:YAML frontmatter + Markdown body 的必需入口点 渐进式披露:启动时加载元数据、触发正文、按需资源 捆绑资源:可选
scripts/、references/、assets/目录 按需加载:Agent 调用skill({ name: "skill-name" })加载参考文件结构
文件 · 目的 · 何时阅读
quickstart.md· 最低限度的技能,目录设置 · 创建第一个技能frontmatter.md· YAML 规范、验证规则、描述编写 · 编写 frontmatterstructure.md· 正文模式、章节模板、内容模式 · 组织内容progressive-disclosure.md· 三级加载、拆分 · 管理代币预算阅读顺序
创造技能?从
quickstart.md开始,然后frontmatter.md构建内容?阅读structure.md,然后阅读progressive-disclosure.md添加资源?请参阅references-resources.md测试和改进?请参阅testing-iteration.md有问题吗?首先检查gotchas.mdFrontmatter 验证规则
字段 · 必填 · 约束
name· 是 · 小写字母数字 + 连字符,1-64 个字符,无前导/尾随/连续连字符description· 是 · 1-1024 个字符,无尖括号 (<>),包括内容 + 何时metadata· 否 · 键值对(字符串)内容限制
组件 · 限制 · 注释 名称 · 64 个字符 · 小写连字符大小写 说明(前文) · 250 个字符 · 硬限制 — 在系统提示符中截断为 250 个字符;所有代理都可以看到此描述(正文)·~500 个字符·完整描述为
# Title之后的普通段落;加载技能 SKILL.md 主体 · <500 行 · 指导方针,不强制执行