skill-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Architecture

技能架构

Comprehensive guide for creating effective Claude Code skills following Anthropic's official standards with emphasis on security, CLI-specific features, and progressive disclosure architecture.

⚠️ Scope: Claude Code CLI Agent Skills (
~/.claude/skills/
), not Claude.ai API skills

本指南详细介绍了如何遵循Anthropic官方标准创建高效的Claude Code技能，重点关注安全性、CLI专属特性和渐进式披露架构。

⚠️ 适用范围：Claude Code CLI Agent技能（存储于
~/.claude/skills/
），而非Claude.ai API技能

When to Use This Skill

何时使用本技能

Use this skill when:

Creating new Claude Code skills from scratch
Learning skill YAML frontmatter and structure requirements
Validating skill file format and portability
Understanding progressive disclosure patterns for skills

在以下场景使用本技能：

从零开始创建新的Claude Code技能
学习技能的YAML前置元数据和结构要求
验证技能文件格式与可移植性
理解技能的渐进式披露模式

FIRST: TodoWrite Task Templates

第一步：TodoWrite任务模板

MANDATORY: Select and load the appropriate template into TodoWrite before any skill work.

For detailed context on each step, see Skill Creation Process (Detailed Tutorial) below.

强制要求：在开展任何技能开发工作前，选择并加载合适的模板到TodoWrite中。

如需了解每个步骤的详细背景，请参阅下方的【技能创建流程（详细教程）】。

Template A: Create New Skill

模板A：创建新技能

1. Gather requirements (ask user for functionality, examples, triggers)
2. Identify reusable resources (scripts, references, assets needed)
3. Run init script to create skill directory structure
4. Create bundled resources first (scripts/, references/, assets/)
5. Write SKILL.md with YAML frontmatter (name, description with triggers)
6. Add TodoWrite task templates section to SKILL.md
7. Add Post-Change Checklist section to SKILL.md
8. Validate with quick_validate.py
9. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
10. Test skill on real example
11. Register skill in project CLAUDE.md
12. Verify against Skill Quality Checklist below

1. 收集需求（向用户询问功能、示例、触发词）
2. 识别可复用资源（所需的脚本、参考资料、资产）
3. 运行初始化脚本创建技能目录结构
4. 先创建捆绑资源（scripts/、references/、assets/）
5. 编写带有YAML前置元数据的SKILL.md（包含名称、带触发词的描述）
6. 在SKILL.md中添加TodoWrite任务模板章节
7. 在SKILL.md中添加变更后检查清单章节
8. 使用quick_validate.py进行验证
9. 验证链接（仅使用相对路径）：bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
10. 在真实示例上测试技能
11. 在项目CLAUDE.md中注册技能
12. 根据下方的技能质量检查清单进行验证

Template B: Update Existing Skill

模板B：更新现有技能

1. Read current SKILL.md and understand structure
2. Identify what needs changing (triggers, workflow, resources)
3. Make targeted changes to SKILL.md
4. Update any affected references/ or scripts/
5. Validate with quick_validate.py
6. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
7. Test updated behavior
8. Update project CLAUDE.md if description changed
9. Verify against Skill Quality Checklist below

1. 阅读当前SKILL.md并理解其结构
2. 确定需要修改的内容（触发词、工作流、资源）
3. 对SKILL.md进行针对性修改
4. 更新所有受影响的references/或scripts/内容
5. 使用quick_validate.py进行验证
6. 验证链接（仅使用相对路径）：bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
7. 测试更新后的行为
8. 若描述有变更，更新项目CLAUDE.md
9. 根据下方的技能质量检查清单进行验证

Template C: Add Resources to Skill

模板C：为技能添加资源

1. Read current SKILL.md to understand skill purpose
2. Determine resource type (script, reference, or asset)
3. Create resource in appropriate directory
4. Update SKILL.md to document new resource
5. Validate with quick_validate.py
6. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
7. Test resource integration
8. Verify against Skill Quality Checklist below

1. 阅读当前SKILL.md以理解技能用途
2. 确定资源类型（脚本、参考资料或资产）
3. 在对应目录中创建资源
4. 更新SKILL.md以记录新资源
5. 使用quick_validate.py进行验证
6. 验证链接（仅使用相对路径）：bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
7. 测试资源集成效果
8. 根据下方的技能质量检查清单进行验证

Template D: Convert to Self-Evolving Skill

模板D：转换为自演进技能

1. Read current SKILL.md structure
2. Add TodoWrite Task Templates section (scenario-specific)
3. Add Post-Change Checklist section
4. Create references/evolution-log.md (reverse chronological - newest on top)
5. Create references/config-reference.md (if skill manages external config)
6. Update description with self-evolution triggers
7. Validate with quick_validate.py
8. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
9. Test self-documentation on sample change
10. Verify against Skill Quality Checklist below

1. 阅读当前SKILL.md结构
2. 添加TodoWrite任务模板章节（按场景划分）
3. 添加变更后检查清单章节
4. 创建references/evolution-log.md（按逆时间顺序排列 - 最新内容在顶部）
5. 创建references/config-reference.md（若技能管理外部配置）
6. 更新描述以包含自演进触发词
7. 使用quick_validate.py进行验证
8. 验证链接（仅使用相对路径）：bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
9. 在示例变更上测试自文档功能
10. 根据下方的技能质量检查清单进行验证

Template E: Troubleshoot Skill Not Triggering

模板E：排查技能未触发问题

1. Check YAML frontmatter syntax (no colons in description)
2. Verify trigger keywords in description match user queries
3. Check skill location (~/.claude/skills/ or project .claude/skills/)
4. Validate with quick_validate.py for errors
5. Validate links: bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
6. Test with explicit trigger phrase
7. Document findings in skill if new issue discovered
8. Verify against Skill Quality Checklist below

1. 检查YAML前置元数据语法（描述中不能有冒号）
2. 验证描述中的触发词是否匹配用户查询
3. 检查技能位置（~/.claude/skills/ 或项目的.claude/skills/）
4. 使用quick_validate.py验证是否存在错误
5. 验证链接：bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
6. 使用明确的触发短语进行测试
7. 若发现新问题，在技能中记录相关发现
8. 根据下方的技能质量检查清单进行验证

Skill Quality Checklist

技能质量检查清单

After ANY skill work, verify:

YAML frontmatter valid (name lowercase-hyphen, description has triggers)
Description includes WHEN to use (trigger keywords)
TodoWrite templates cover all common scenarios
Post-Change Checklist included for self-maintenance
Final template step references this checklist
Project CLAUDE.md updated if new/renamed skill
Validated with quick_validate.py
All markdown links use relative paths (plugin-portable)
No broken internal links (validate-links.ts passes)
No unsafe path patterns (see Path Patterns):
- No hardcoded
```
/Users/<user>
```
  or
```
/home/<user>
```
  (use
```
$HOME
```
  )
- No hardcoded
```
/tmp
```
  in Python (use
```
tempfile.TemporaryDirectory
```
  )
- No hardcoded binary paths (use
```
command -v
```
  or PATH)
Bash compatibility verified (see Bash Compatibility):
- All bash code blocks wrapped with
```
/usr/bin/env bash << 'NAME_EOF'
```
- No
```
declare -A
```
  (associative arrays) - use parallel indexed arrays
- No
```
grep -P
```
  (Perl regex) - use
```
grep -E
```
  with awk
- No
```
\!=
```
  in conditionals - use
```
!=
```
  directly
- Heredoc EOF marker is descriptive (e.g.,
```
PREFLIGHT_EOF
```
  )

完成任何技能相关工作后，请验证以下内容：

YAML前置元数据有效（名称为小写连字符格式，描述包含触发词）
描述包含使用场景（触发词）
TodoWrite模板覆盖所有常见场景
包含用于自维护的变更后检查清单
模板最后一步引用本检查清单
若技能新增或重命名，已更新项目CLAUDE.md
已使用quick_validate.py验证
所有Markdown链接使用相对路径（支持插件移植）
无内部断链（validate-links.ts验证通过）
无不安全路径模式（请参阅【路径模式】./references/path-patterns.md）：
- 无硬编码的
```
/Users/<user>
```
  或
```
/home/<user>
```
  （使用
```
$HOME
```
  ）
- Python代码中无硬编码的
```
/tmp
```
  （使用
```
tempfile.TemporaryDirectory
```
  ）
- 无硬编码的二进制路径（使用
```
command -v
```
  或PATH）
已验证Bash兼容性（请参阅【Bash兼容性】./references/bash-compatibility.md）：
- 所有Bash代码块使用
```
/usr/bin/env bash << 'NAME_EOF'
```
  包裹
- 不使用
```
declare -A
```
  （关联数组）- 使用并行索引数组
- 不使用
```
grep -P
```
  （Perl正则）- 使用
```
grep -E
```
  搭配awk
- 条件语句中不使用
```
\!=
```
  - 直接使用
```
!=
```
- heredoc的EOF标记具有描述性（例如
```
PREFLIGHT_EOF
```
  ）

Post-Change Checklist (Self-Maintenance)

变更后检查清单（自维护）

Continuous Improvement (Proactive Self-Evolution)

持续改进（主动自演进）

CRITICAL: Skills must actively evolve. Don't wait for explicit requests—upgrade skills when insights emerge.

关键要求：技能必须主动演进。不要等待明确的请求——当获得新见解时就升级技能。

During Every Skill Execution

在每次技能执行期间

Watch for these improvement signals:

Signal	Example	Action
Friction	Step feels awkward or unclear	Rewrite for clarity
Missing edge case	Workflow fails on valid input	Add handling + document
Better pattern	Discover more elegant approach	Update + log why
User confusion	Same question asked repeatedly	Add clarification or FAQ
Tool evolution	Underlying tool gains features	Update to leverage them
Repeated manual steps	Same code written each time	Create script in `scripts/`

留意以下改进信号：

信号	示例	操作
操作阻力	步骤感觉生硬或不清晰	重写以提升清晰度
缺失边缘场景处理	工作流在有效输入下失败	添加处理逻辑并记录
更优模式	发现更简洁的实现方式	更新并记录原因
用户困惑	重复被问到相同问题	添加说明或FAQ
工具演进	底层工具新增功能	更新以利用新功能
重复手动步骤	每次都要编写相同代码	在 `scripts/` 中创建脚本

Immediate Update Protocol

即时更新流程

When improvement opportunity identified:

Pause current task (briefly)
Make the improvement to SKILL.md or resources
Log in evolution-log.md (one-liner is fine for small changes)
Resume original task

Rationale: Small immediate updates compound. Waiting means insights are forgotten. 30 seconds now saves 5 minutes later.

当发现改进机会时：

暂停当前任务（短暂暂停）
实施改进到SKILL.md或资源中
记录到evolution-log.md（小变更只需一行记录即可）
恢复原任务

原理：小的即时更新会不断积累。等待会导致见解被遗忘。现在花30秒，以后能节省5分钟。

What NOT to Update Immediately

无需即时更新的情况

Major structural changes (discuss with user first)
Changes that would break in-progress work
Speculative improvements without concrete evidence

重大结构变更（先与用户讨论）
会中断进行中工作的变更
无具体依据的推测性改进

Self-Reflection Trigger

自我反思触发点

After completing any skill-assisted task, ask:

"Did anything about this skill feel suboptimal? If I encountered this again, what would help?"

If answer exists → update the skill NOW.

完成任何技能辅助任务后，请自问：

"本技能的某些部分是否感觉不够理想？如果再次遇到这种情况，什么会有所帮助？"

若有答案→立即更新技能。

About Skills

关于技能

Skills are modular, self-contained packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains—transforming Claude from general-purpose to specialized agent with procedural knowledge no model fully possesses.

技能是模块化、独立的包，通过专业知识、工作流和工具扩展Claude的能力。可以将其视为特定领域的“入门指南”——将Claude从通用型Agent转变为具备程序知识的专用Agent，而这些知识是任何模型都无法完全拥有的。

What Skills Provide

技能提供的能力

Specialized workflows - Multi-step procedures for specific domains
Tool integrations - Instructions for working with specific file formats or APIs
Domain expertise - Company-specific knowledge, schemas, business logic
Bundled resources - Scripts, references, assets for complex/repetitive tasks

专业工作流 - 特定领域的多步骤流程
工具集成 - 与特定文件格式或API协作的说明
领域专业知识 - 公司专属知识、 schema、业务逻辑
捆绑资源 - 用于复杂/重复任务的脚本、参考资料、资产

Skill Creation Process (Detailed Tutorial)

技能创建流程（详细教程）

Note: Use TodoWrite templates above for execution. This section provides detailed context for each phase.

注意：执行时请使用上方的TodoWrite模板。本节为每个阶段提供详细背景信息。

Step 1: Understanding the Skill with Concrete Examples

步骤1：通过具体示例理解技能

Clearly understand concrete examples of how the skill will be used. Ask users:

"What functionality should this skill support?"
"Can you give examples of how it would be used?"
"What would trigger this skill?"

Skip only when usage patterns are already clearly understood.

清晰理解技能的具体使用示例。向用户询问：

"该技能应支持哪些功能？"
"能否提供使用示例？"
"什么会触发该技能？"

仅当使用模式已明确时可跳过此步骤。

Step 2: Planning Reusable Contents

步骤2：规划可复用内容

Analyze each example to identify what resources would be helpful:

Example 1 - PDF Editor:

Rotating PDFs requires rewriting code each time
→ Create
```
scripts/rotate_pdf.py
```

Example 2 - Frontend Builder:

Webapps need same HTML/React boilerplate
→ Create
```
assets/hello-world/
```
template

Example 3 - BigQuery:

Queries require rediscovering table schemas
→ Create
```
references/schema.md
```

分析每个示例，确定需要哪些资源：

示例1 - PDF编辑器：

每次旋转PDF都需要重写代码
→ 创建
```
scripts/rotate_pdf.py
```

示例2 - 前端构建工具：

Web应用需要相同的HTML/React模板
→ 创建
```
assets/hello-world/
```
模板

示例3 - BigQuery：

查询时需要重新查找表schema
→ 创建
```
references/schema.md
```

Step 3: Initialize the Skill

步骤3：初始化技能

Run the init script from plugin-dev:

bash

uv run plugins/plugin-dev/scripts/skill-creator/init_skill.py <skill-name> --path <target-path>

Creates: skill directory + SKILL.md template + example resource directories

从plugin-dev运行初始化脚本：

bash

uv run plugins/plugin-dev/scripts/skill-creator/init_skill.py <skill-name> --path <target-path>

创建：技能目录 + SKILL.md模板 + 示例资源目录

Step 4: Edit the Skill

步骤4：编辑技能

Writing Style: Imperative/infinitive form (verb-first), not second person

✅ "To accomplish X, do Y"
❌ "You should do X"

SKILL.md must include:

What is the purpose? (few sentences)
When should it be used? (trigger keywords in description)
How should Claude use bundled resources?
TodoWrite Task Templates - Pre-defined todos for common scenarios
Post-Change Checklist - Self-maintenance verification

Start with resources (

scripts/

references/

assets/

), then update SKILL.md

写作风格：使用命令式/不定式形式（动词开头），而非第二人称

✅ "要完成X，请执行Y"
❌ "你应该做X"

SKILL.md必须包含：

用途是什么？（几句话）
何时使用？（描述中包含触发词）
Claude应如何使用捆绑资源？
TodoWrite任务模板 - 针对常见场景的预定义待办事项
变更后检查清单 - 自维护验证项

先创建资源（

scripts/

、

references/

、

assets/

），再更新SKILL.md

Step 5: Validate the Skill

步骤5：验证技能

For local development (validation only, no zip creation):

bash

uv run plugins/plugin-dev/scripts/skill-creator/quick_validate.py <path/to/skill-folder>

For distribution (validates AND creates zip):

bash

uv run plugins/plugin-dev/scripts/skill-creator/package_skill.py <path/to/skill-folder>

Validates: YAML frontmatter, naming, description, file organization

Note: Use

quick_validate.py

for most workflows. Only use

package_skill.py

when actually distributing the skill to others.

本地开发时（仅验证，不创建zip包）：

bash

uv run plugins/plugin-dev/scripts/skill-creator/quick_validate.py <path/to/skill-folder>

分发时（验证并创建zip包）：

bash

uv run plugins/plugin-dev/scripts/skill-creator/package_skill.py <path/to/skill-folder>

验证内容：YAML前置元数据、命名、描述、文件组织结构

注意：大多数工作流使用

quick_validate.py

。仅在实际向他人分发技能时使用

package_skill.py

。

Step 6: Register and Iterate

步骤6：注册与迭代

Register skill in project CLAUDE.md (Workspace Skills section)
Use skill on real tasks
Notice struggles/inefficiencies
Update SKILL.md or resources
Test again
Verify against Skill Quality Checklist above

在项目CLAUDE.md的【工作区技能】章节注册技能
在真实任务中使用技能
留意使用中的困难/低效点
更新SKILL.md或资源
再次测试
根据上方的技能质量检查清单验证

Skill Anatomy

技能结构

skill-name/
├── SKILL.md                      # Required: YAML frontmatter + instructions
├── scripts/                      # Optional: Executable code (Python/Bash)
├── references/                   # Optional: Documentation loaded as needed
│   └── evolution-log.md          # Recommended: Change history (self-evolving)
└── assets/                       # Optional: Files used in output

skill-name/
├── SKILL.md                      # 必填：YAML前置元数据 + 说明文档
├── scripts/                      # 可选：可执行代码（Python/Bash）
├── references/                   # 可选：按需加载的文档
│   └── evolution-log.md          # 推荐：变更历史（支持自演进）
└── assets/                       # 可选：输出中使用的文件

YAML Frontmatter (Required)

YAML前置元数据（必填）

yaml

---
name: skill-name-here
description: What this does and when to use it (max 1024 chars for CLI)
allowed-tools: Read, Grep, Bash # Optional, CLI-only feature
---

Field Requirements:

Field	Rules
`name`	Lowercase, hyphens, numbers. Max 64 chars. Unique.
`description`	WHAT it does + WHEN to use. Max 1024 chars (CLI) / 200 (API). Include triggers!
`allowed-tools`	CLI-only. Comma-separated list restricts tools. Optional.

Good vs Bad Descriptions:

✅ Good: "Extract text and tables from PDFs, fill forms, merge documents. Use when working with PDF files or when user mentions forms, contracts, document processing."

❌ Bad: "Helps with documents" (too vague, no triggers)

YAML Description Pitfalls:

Pitfall	Problem	Fix
Multiline syntax	`>` or `\|` not supported	Single line only
Colons in text	`CRITICAL: requires` breaks YAML	Use `CRITICAL - requires`
Quoted strings	Valid but not idiomatic	Unquoted preferred (match anthropics/skills)

yaml

undefined

yaml

---
name: skill-name-here
description: 技能用途与使用场景（CLI版本最多1024字符）
allowed-tools: Read, Grep, Bash # 可选，仅CLI支持
---

字段要求：

字段	规则
`name`	小写、连字符、数字。最多64字符。唯一标识。
`description`	功能 + 使用场景。CLI版本最多1024字符 / API版本最多200字符。必须包含触发词！
`allowed-tools`	仅CLI支持。逗号分隔的工具限制列表。可选。

优秀与糟糕的描述对比：

✅ 优秀："从PDF中提取文本和表格、填写表单、合并文档。处理PDF文件或用户提及表单、合同、文档处理时使用。"

❌ 糟糕："帮助处理文档"（过于模糊，无触发词）

YAML描述常见陷阱：

陷阱	问题	修复方案
多行语法	不支持 `>` 或 `\|`	仅使用单行
文本中的冒号	`CRITICAL: requires` 会破坏YAML	使用 `CRITICAL - requires`
带引号的字符串	合法但不符合惯例	首选无引号格式（匹配anthropics/skills）

yaml

undefined

❌ BREAKS - colon parsed as YAML key:value

❌ 错误 - 冒号会被解析为YAML键值对

description: ...CRITICAL: requires flag

✅ WORKS - dash instead of colon

✅ 正确 - 使用破折号代替冒号

description: ...CRITICAL - requires flag


**Validation**: GitHub renders frontmatter - invalid YAML shows red error banner.

description: ...CRITICAL - requires flag


**验证方式**：GitHub会渲染前置元数据 - 无效YAML会显示红色错误横幅。

Progressive Disclosure (3 Levels)

渐进式披露（3个层级）

Skills use progressive loading to manage context efficiently:

Metadata (name + description) - Always in context (~100 words)
SKILL.md body - When skill triggers (<5k words)
Bundled resources - As needed by Claude (unlimited*)

*Scripts can execute without reading into context.

技能使用渐进式加载以高效管理上下文：

元数据（名称 + 描述）- 始终在上下文中（约100词）
SKILL.md主体 - 技能触发时加载（<5000词）
捆绑资源 - Claude按需加载（无限制*）

*脚本可在不加载到上下文的情况下执行。

Bundled Resources

捆绑资源

Skills can include

scripts/

references/

, and

assets/

directories. See Progressive Disclosure for detailed guidance on when to use each.

技能可包含

scripts/

、

references/

和

assets/

目录。有关何时使用每个目录的详细指南，请参阅【渐进式披露】./references/progressive-disclosure.md。

CLI-Specific Features

CLI专属特性

CLI skills support

allowed-tools

restriction for security. See Security Practices for details.

CLI技能支持

allowed-tools

限制以保障安全性。详情请参阅【安全实践】./references/security-practices.md。

Structural Patterns

结构模式

See Structural Patterns for detailed guidance on:

Workflow Pattern - Sequential multi-step procedures
Task Pattern - Specific, bounded tasks
Reference Pattern - Knowledge repository
Capabilities Pattern - Tool integrations

有关以下内容的详细指南，请参阅【结构模式】./references/structural-patterns.md：

工作流模式 - 顺序多步骤流程
任务模式 - 特定、有界的任务
参考模式 - 知识库
能力模式 - 工具集成

User Conventions Integration

用户约定集成

This skill follows common user conventions:

Absolute paths: Always use full paths (terminal Cmd+click compatible)
Unix-only: macOS, Linux (no Windows support)
Python:
```
uv run script.py
```
with PEP 723 inline dependencies
Planning: OpenAPI 3.1.1 specs when appropriate

本技能遵循常见用户约定：

绝对路径：始终使用完整路径（支持终端Cmd+点击跳转）
仅支持Unix：macOS、Linux（不支持Windows）
Python：使用
```
uv run script.py
```
搭配PEP 723内联依赖
规划：适当情况下使用OpenAPI 3.1.1规范

Marketplace Scripts

市场脚本

See Scripts Reference for marketplace script usage.

有关市场脚本的使用方法，请参阅【脚本参考】./references/scripts-reference.md。

Reference Documentation

参考文档

For detailed information, see:

Structural Patterns - 4 skill architecture patterns
Workflow Patterns - Workflow skill implementation patterns
Progressive Disclosure - Context management patterns
Creation Workflow - Step-by-step process
Scripts Reference - Marketplace script usage
Security Practices - Threats and defenses (CVE references)
Token Efficiency - Context optimization
Advanced Topics - CLI vs API, composition, bugs
Path Patterns - Safe/unsafe path references (known bugs documented)
Validation Reference - Quality checklist
SYNC-TRACKING - Marketplace version tracking
Evolution Log - This skill's change history

如需详细信息，请参阅：

结构模式 - 4种技能架构模式
工作流模式 - 工作流技能实现模式
渐进式披露 - 上下文管理模式
创建工作流 - 分步流程
脚本参考 - 市场脚本使用方法
安全实践 - 威胁与防御（含CVE参考）
Token效率 - 上下文优化
高级主题 - CLI与API对比、组合、bug
路径模式 - 安全/不安全路径参考（已记录已知bug）
验证参考 - 质量检查清单
SYNC-TRACKING - 市场版本跟踪
演进日志 - 本技能的变更历史

Troubleshooting

故障排查

Issue	Cause	Solution
Skill not triggering	Missing trigger keywords	Add trigger phrases to description field
YAML parse error	Colon in description	Replace colons with dashes in description
Skill not found	Wrong location	Place in `~/.claude/skills/` or project `.claude/skills/`
validate script fails	Invalid frontmatter	Check name format (lowercase-hyphen only)
Resources not loading	Wrong path in SKILL.md	Use relative paths from skill directory
Script execution fails	Missing shebang or permissions	Add `#!/usr/bin/env python3` and `chmod +x`
allowed-tools ignored	API skill (not CLI)	allowed-tools only works in CLI skills
Description too long	Over 1024 chars	Shorten description, move details to SKILL.md body

问题	原因	解决方案
技能未触发	缺少触发关键词	在描述字段中添加触发短语
YAML解析错误	描述中包含冒号	将描述中的冒号替换为破折号
技能未找到	位置错误	放置在 `~/.claude/skills/` 或项目的.claude/skills/目录中
验证脚本执行失败	前置元数据无效	检查名称格式（仅小写连字符）
资源无法加载	SKILL.md中的路径错误	使用相对于技能目录的相对路径
脚本执行失败	缺少shebang或权限	添加 `#!/usr/bin/env python3` 并执行 `chmod +x`
allowed-tools设置被忽略	API技能（非CLI）	allowed-tools仅在CLI技能中生效
描述过长	超过1024字符	缩短描述，将详细内容移至SKILL.md主体