skill-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Agent Skills Best Practices

AI Agent技能最佳实践

Design and development guide for AI agent skills, including Claude Code skills and MCP tools. Contains 46 rules across 8 categories, prioritized by impact to guide skill creation, review, and optimization.

Claude Code技能及MCP工具的AI Agent技能设计与开发指南。包含8个类别共46条规则，按影响优先级排序，用于指导技能的创建、评审与优化。

When to Apply

适用场景

Creating new Claude Code skills or MCP tools
Writing or reviewing SKILL.md metadata and descriptions
Optimizing skill trigger reliability
Structuring content for progressive disclosure
Testing skill activation and behavior
Designing tool interfaces for agent workflows

创建新的Claude Code技能或MCP工具
编写或评审SKILL.md元数据与描述
优化技能触发的可靠性
为渐进式披露构建内容结构
测试技能的激活与行为
为Agent工作流设计工具界面

Core Principles

核心原则

1. Descriptions drive activation. Claude selects skills based on description matching against user intent. Include specific capabilities, trigger keywords, and negative cases. A skill with a vague description activates inconsistently or never.

2. Front-load critical instructions. Claude may truncate long content. Place non-negotiable rules in the first 100 lines. Bury important constraints at the end and they get ignored.

3. Progressive disclosure saves tokens. Load detailed content only when needed. A 2000-line skill wastes context on every activation. Structure as: SKILL.md (overview) → references/ (details) → scripts/ (execution).

4. Test activation, not just execution. A skill that works perfectly but never triggers provides zero value. Test with real user phrases, synonyms, and edge cases before deployment.

5. One skill per domain. Overlapping skills create activation conflicts. Split by clear boundaries (language, framework, workflow stage) with distinct trigger keywords.

1. 描述驱动激活。Claude会根据描述与用户意图的匹配度选择技能。需包含具体能力、触发关键词及排除场景。描述模糊的技能激活效果不稳定或无法激活。

2. 前置关键指令。Claude可能会截断长内容。将不可协商的规则放在前100行。若重要约束放在末尾，会被忽略。

3. 渐进式披露节省令牌。仅在需要时加载详细内容。一个2000行的技能会在每次激活时浪费上下文。建议结构为：SKILL.md（概述）→ references/（详情）→ scripts/（执行代码）。

4. 测试激活而非仅执行。一个执行完美但从未触发的技能毫无价值。部署前需用真实用户语句、同义词及边缘案例进行测试。

5. 单一领域对应单一技能。重叠技能会导致激活冲突。需按清晰边界（语言、框架、工作流阶段）拆分，使用独特触发关键词。

Rule Categories

规则类别


meta-
desc-
struct-
trigger-
prog-
mcp-
test-
maint-

Priority	Category	Impact	Prefix
1	Skill Metadata Design	CRITICAL	`meta-`
2	Description Engineering	CRITICAL	`desc-`
3	Content Structure	HIGH	`struct-`
4	Trigger Optimization	HIGH	`trigger-`
5	Progressive Disclosure	MEDIUM-HIGH	`prog-`
6	MCP Tool Design	MEDIUM	`mcp-`
7	Testing and Validation	MEDIUM	`test-`
8	Maintenance and Distribution	LOW-MEDIUM	`maint-`


meta-
desc-
struct-
trigger-
prog-
mcp-
test-
maint-

优先级	类别	影响程度	前缀
1	技能元数据设计	关键	`meta-`
2	描述工程	关键	`desc-`
3	内容结构	高	`struct-`
4	触发优化	高	`trigger-`
5	渐进式披露	中高	`prog-`
6	MCP工具设计	中	`mcp-`
7	测试与验证	中	`test-`
8	维护与分发	中低	`maint-`

Quick Reference

快速参考

1. Skill Metadata Design (CRITICAL)

1. 技能元数据设计（关键）

```
meta-name-format
```
- Use lowercase hyphenated skill names
```
meta-name-hyphen-boundaries
```
- Never start or end names with hyphens
```
meta-name-no-consecutive-hyphens
```
- Avoid consecutive hyphens in names
```
meta-name-uniqueness
```
- Ensure skill names are globally unique
```
meta-required-frontmatter
```
- Include all required frontmatter fields
```
meta-allowed-frontmatter-fields
```
- Use only allowed frontmatter fields
```
meta-frontmatter-yaml-syntax
```
- Use valid YAML frontmatter syntax
```
meta-name-length
```
- Keep skill names under 64 characters
```
meta-directory-match
```
- Match skill name to directory name

```
meta-name-format
```
- 使用小写连字符分隔的技能名称
```
meta-name-hyphen-boundaries
```
- 技能名称首尾不能使用连字符
```
meta-name-no-consecutive-hyphens
```
- 避免技能名称中出现连续连字符
```
meta-name-uniqueness
```
- 确保技能名称全局唯一
```
meta-required-frontmatter
```
- 包含所有必填的前置元数据字段
```
meta-allowed-frontmatter-fields
```
- 仅使用允许的前置元数据字段
```
meta-frontmatter-yaml-syntax
```
- 使用有效的YAML前置元数据语法
```
meta-name-length
```
- 技能名称长度保持在64字符以内
```
meta-directory-match
```
- 技能名称需与目录名称匹配

2. Description Engineering (CRITICAL)

2. 描述工程（关键）

```
desc-specific-capabilities
```
- Name specific capabilities in description
```
desc-trigger-keywords
```
- Include user trigger keywords in description
```
desc-third-person-voice
```
- Write descriptions in third person
```
desc-length-optimization
```
- Optimize description length for discovery
```
desc-avoid-vague-terms
```
- Avoid vague terms in descriptions
```
desc-differentiate-similar-skills
```
- Differentiate similar skills with distinct triggers
```
desc-include-negative-cases
```
- Include negative cases for precision

```
desc-specific-capabilities
```
- 在描述中明确列出具体能力
```
desc-trigger-keywords
```
- 在描述中包含用户触发关键词
```
desc-third-person-voice
```
- 使用第三人称撰写描述
```
desc-length-optimization
```
- 优化描述长度以提升可发现性
```
desc-avoid-vague-terms
```
- 描述中避免使用模糊术语
```
desc-differentiate-similar-skills
```
- 通过独特触发词区分相似技能
```
desc-include-negative-cases
```
- 包含排除场景以提高精准度

3. Content Structure (HIGH)

3. 内容结构（高）

```
struct-header-hierarchy
```
- Use consistent header hierarchy
```
struct-instructions-first
```
- Put critical instructions early in content
```
struct-imperative-instructions
```
- Write instructions in imperative mood
```
struct-code-blocks-with-language
```
- Specify language in code blocks
```
struct-line-limit
```
- Keep SKILL.md under 500 lines
```
struct-single-responsibility
```
- One skill per domain

```
struct-header-hierarchy
```
- 使用一致的标题层级
```
struct-instructions-first
```
- 将关键指令放在内容前部
```
struct-imperative-instructions
```
- 使用祈使语气撰写指令
```
struct-code-blocks-with-language
```
- 在代码块中指定语言
```
struct-line-limit
```
- SKILL.md文件行数保持在500行以内
```
struct-single-responsibility
```
- 单一技能对应单一领域

4. Trigger Optimization (HIGH)

4. 触发优化（高）

```
trigger-slash-command-aliases
```
- Include slash command aliases in description
```
trigger-file-type-patterns
```
- Include file type patterns in description
```
trigger-workflow-stages
```
- Reference workflow stages in description
```
trigger-error-patterns
```
- Include error patterns in debugging skills
```
trigger-synonym-coverage
```
- Cover synonyms and alternate phrasings

```
trigger-slash-command-aliases
```
- 在描述中包含斜杠命令别名
```
trigger-file-type-patterns
```
- 在描述中包含文件类型模式
```
trigger-workflow-stages
```
- 在描述中提及工作流阶段
```
trigger-error-patterns
```
- 在调试技能中包含错误模式
```
trigger-synonym-coverage
```
- 覆盖同义词及替代表述

5. Progressive Disclosure (MEDIUM-HIGH)

5. 渐进式披露（中高）

```
prog-three-level-disclosure
```
- Implement three-level progressive disclosure
```
prog-one-level-deep-links
```
- Limit reference links to one level deep
```
prog-scripts-execute-not-read
```
- Execute scripts instead of reading code
```
prog-lazy-load-examples
```
- Lazy load examples and reference material
```
prog-mutual-exclusion
```
- Separate mutually exclusive contexts

```
prog-three-level-disclosure
```
- 实现三级渐进式披露
```
prog-one-level-deep-links
```
- 限制参考链接深度为一级
```
prog-scripts-execute-not-read
```
- 执行脚本而非读取代码
```
prog-lazy-load-examples
```
- 延迟加载示例及参考资料
```
prog-mutual-exclusion
```
- 分离互斥上下文

6. MCP Tool Design (MEDIUM)

6. MCP工具设计（中）

```
mcp-tool-naming
```
- Use clear action-object tool names
```
mcp-parameter-descriptions
```
- Document all tool parameters
```
mcp-error-messages
```
- Return actionable error messages
```
mcp-tool-scope
```
- Design single-purpose tools
```
mcp-allowed-tools
```
- Use allowed-tools for safety constraints
```
mcp-idempotent-operations
```
- Design idempotent tool operations

```
mcp-tool-naming
```
- 使用清晰的“动作-对象”式工具名称
```
mcp-parameter-descriptions
```
- 记录所有工具参数
```
mcp-error-messages
```
- 返回可执行的错误信息
```
mcp-tool-scope
```
- 设计单一用途的工具
```
mcp-allowed-tools
```
- 使用allowed-tools设置安全约束
```
mcp-idempotent-operations
```
- 设计幂等操作的工具

7. Testing and Validation (MEDIUM)

7. 测试与验证（中）

```
test-trigger-phrases
```
- Test skill activation with real user phrases
```
test-edge-cases
```
- Test skills with edge case inputs
```
test-negative-scenarios
```
- Test that skills do NOT trigger on unrelated requests
```
test-instruction-clarity
```
- Test instructions with fresh context

```
test-trigger-phrases
```
- 使用真实用户语句测试技能激活
```
test-edge-cases
```
- 使用边缘案例输入测试技能
```
test-negative-scenarios
```
- 测试技能在无关请求下不触发
```
test-instruction-clarity
```
- 在全新上下文下测试指令清晰度

8. Maintenance and Distribution (LOW-MEDIUM)

8. 维护与分发（中低）

```
maint-semantic-versioning
```
- Use semantic versioning for skill releases
```
maint-changelog
```
- Maintain a changelog for skill updates
```
maint-plugin-packaging
```
- Package skills as plugins for distribution
```
maint-audit-security
```
- Audit skills before installing from external sources

```
maint-semantic-versioning
```
- 为技能版本使用语义化版本控制
```
maint-changelog
```
- 维护技能更新的变更日志
```
maint-plugin-packaging
```
- 将技能打包为插件进行分发
```
maint-audit-security
```
- 安装外部来源的技能前进行安全审计

Creating Rules

创建规则

Copy assets/templates/_template.md and follow the frontmatter schema:

yaml

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---

Reference files use the pattern:

references/{prefix}-{slug}.md

复制assets/templates/_template.md并遵循前置元数据 schema：