skill-design-philosophy
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSkill Design Philosophy
技能设计原则
Skills provide knowledge and context, not autonomous execution.
Skill提供知识与上下文，而非自主执行能力。
The Knowledge Test
知识测试
Ask: "Does this TEACH Claude or DO something?"
| TEACH (Skill) | DO (Agent) |
|---|---|
| Coding conventions | Run linters and fix code |
| Workflow methodology | Execute multi-step processes |
| Framework patterns | Generate reports |
| Tool usage guidance | Fetch and analyze data |
Rule: If it produces artifacts without user guidance, it's probably an agent.
问：“这是在向Claude传授知识，还是让它执行任务？”
| 传授（Skill） | 执行（Agent） |
|---|---|
| 编码规范 | 运行代码检查工具并修复代码 |
| 工作流方法论 | 执行多步骤流程 |
| 框架模式 | 生成报告 |
| 工具使用指南 | 获取并分析数据 |
规则： 如果无需用户指导即可生成成果，那它很可能是Agent。
Good Skill Examples
优秀Skill示例
| Skill | Why It Works |
|---|---|
| Coding style guidance - patterns Claude applies when writing code |
| Methodology knowledge - steps Claude follows for test-driven development |
| Framework patterns - conventions Claude uses for Stimulus controllers |
| Tool knowledge - how to use specific libraries and scripts |
Pattern: Skills TEACH Claude patterns, conventions, and approaches.
| Skill | 优势原因 |
|---|---|
| 编码风格指导——Claude编写代码时遵循的模式 |
| 方法论知识——Claude进行测试驱动开发的步骤 |
| 框架模式——Claude编写Stimulus控制器时遵循的规范 |
| 工具知识——如何使用特定库与脚本 |
模式： Skill向Claude传授模式、规范与方法。
Bad Skill Examples
不良Skill示例
| Skill | Why It Fails |
|---|---|
| "Code reviewer" | Does autonomous work - should be an agent |
| "Git helper" | Vague scope - what specifically does it teach? |
| "Best practices" | Too broad - not actionable |
| "Documentation generator" | Creates artifacts - should be an agent |
Pattern: These skills DO things instead of TEACHING things.
| Skill | 失败原因 |
|---|---|
| "Code reviewer" | 自主完成工作——应作为Agent |
| "Git helper" | 范围模糊——具体传授什么内容？ |
| "Best practices" | 过于宽泛——不具备可操作性 |
| "Documentation generator" | 生成成果——应作为Agent |
模式： 这些Skill是在执行任务而非传授知识。
Content Rules
内容规则
| Include | Exclude |
|---|---|
| Concrete patterns and conventions | Persona statements ("You are an expert...") |
| Specific templates and examples | Attribution ("Inspired by X...") |
| Decision criteria | Decorative quotes |
| Error handling guidance | ASCII art or box-drawing |
| Framework-specific idioms | Vague "best practices" |
| 需包含 | 需排除 |
|---|---|
| 具体的模式与规范 | 角色声明（“你是专家...”） |
| 特定模板与示例 | 引用说明（“受X启发...”） |
| 决策标准 | 装饰性引用 |
| 错误处理指南 | ASCII艺术或框线图形 |
| 框架特定的惯用写法 | 模糊的“最佳实践” |
Quality Test
质量测试
"Does every line in this skill improve Claude's behavior?"
If any line is decorative, inspirational, or redundant - cut it.
“该技能中的每一行内容是否都能改善Claude的表现？”
如果任何一行是装饰性、激励性或冗余内容——删除它。