Back to Details

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)

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

After modifying THIS skill (skill-architecture):
  1. Templates and 6 Steps tutorial remain aligned
  2. Skill Quality Checklist reflects current best practices
  3. All referenced files in references/ exist
  4. Append changes to evolution-log.md
  5. Update user's CLAUDE.md if triggers changed
修改本技能（skill-architecture）后：
  1. 模板与6步教程保持一致
  2. 技能质量检查清单反映当前最佳实践
  3. references/中所有引用文件均存在
  4. 将变更记录到【evolution-log.md】./references/evolution-log.md
  5. 若触发词变更，更新用户的CLAUDE.md

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:
SignalExampleAction
FrictionStep feels awkward or unclearRewrite for clarity
Missing edge caseWorkflow fails on valid inputAdd handling + document
Better patternDiscover more elegant approachUpdate + log why
User confusionSame question asked repeatedlyAdd clarification or FAQ
Tool evolutionUnderlying tool gains featuresUpdate to leverage them
Repeated manual stepsSame code written each timeCreate script in 
scripts/
留意以下改进信号：
信号示例操作
操作阻力步骤感觉生硬或不清晰重写以提升清晰度
缺失边缘场景处理工作流在有效输入下失败添加处理逻辑并记录
更优模式发现更简洁的实现方式更新并记录原因
用户困惑重复被问到相同问题添加说明或FAQ
工具演进底层工具新增功能更新以利用新功能
重复手动步骤每次都要编写相同代码在
scripts/
中创建脚本

Immediate Update Protocol

即时更新流程

When improvement opportunity identified:
  1. Pause current task (briefly)
  2. Make the improvement to SKILL.md or resources
  3. Log in evolution-log.md (one-liner is fine for small changes)
  4. Resume original task
Rationale: Small immediate updates compound. Waiting means insights are forgotten. 30 seconds now saves 5 minutes later.
当发现改进机会时：
  1. 暂停当前任务（短暂暂停）
  2. 实施改进到SKILL.md或资源中
  3. 记录到evolution-log.md（小变更只需一行记录即可）
  4. 恢复原任务
原理：小的即时更新会不断积累。等待会导致见解被遗忘。现在花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

技能提供的能力

  1. Specialized workflows - Multi-step procedures for specific domains
  2. Tool integrations - Instructions for working with specific file formats or APIs
  3. Domain expertise - Company-specific knowledge, schemas, business logic
  4. Bundled resources - Scripts, references, assets for complex/repetitive tasks
  1. 专业工作流 - 特定领域的多步骤流程
  2. 工具集成 - 与特定文件格式或API协作的说明
  3. 领域专业知识 - 公司专属知识、 schema、业务逻辑
  4. 捆绑资源 - 用于复杂/重复任务的脚本、参考资料、资产

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:
  1. What is the purpose? (few sentences)
  2. When should it be used? (trigger keywords in description)
  3. How should Claude use bundled resources?
  4. TodoWrite Task Templates - Pre-defined todos for common scenarios
  5. Post-Change Checklist - Self-maintenance verification
Start with resources (
scripts/
, 
references/
, 
assets/
), then update SKILL.md
写作风格：使用命令式/不定式形式（动词开头），而非第二人称
  • ✅ "要完成X，请执行Y"
  • ❌ "你应该做X"
SKILL.md必须包含：
  1. 用途是什么？（几句话）
  2. 何时使用？（描述中包含触发词）
  3. Claude应如何使用捆绑资源？
  4. TodoWrite任务模板 - 针对常见场景的预定义待办事项
  5. 变更后检查清单 - 自维护验证项
先创建资源（
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：注册与迭代

  1. Register skill in project CLAUDE.md (Workspace Skills section)
  2. Use skill on real tasks
  3. Notice struggles/inefficiencies
  4. Update SKILL.md or resources
  5. Test again
  6. Verify against Skill Quality Checklist above
  1. 在项目CLAUDE.md的【工作区技能】章节注册技能
  2. 在真实任务中使用技能
  3. 留意使用中的困难/低效点
  4. 更新SKILL.md或资源
  5. 再次测试
  6. 根据上方的技能质量检查清单验证

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:
FieldRules
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:
PitfallProblemFix
Multiline syntax
>
or 
|
not supported		Single line only
Colons in text
CRITICAL: requires
breaks YAML		Use 
CRITICAL - requires
Quoted stringsValid but not idiomaticUnquoted 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
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:
  1. Metadata (name + description) - Always in context (~100 words)
  2. SKILL.md body - When skill triggers (<5k words)
  3. Bundled resources - As needed by Claude (unlimited*)
*Scripts can execute without reading into context.
技能使用渐进式加载以高效管理上下文：
  1. 元数据（名称 + 描述）- 始终在上下文中（约100词）
  2. SKILL.md主体 - 技能触发时加载（<5000词）
  3. 捆绑资源 - 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:
  1. Workflow Pattern - Sequential multi-step procedures
  2. Task Pattern - Specific, bounded tasks
  3. Reference Pattern - Knowledge repository
  4. Capabilities Pattern - Tool integrations
有关以下内容的详细指南，请参阅【结构模式】./references/structural-patterns.md：
  1. 工作流模式 - 顺序多步骤流程
  2. 任务模式 - 特定、有界的任务
  3. 参考模式 - 知识库
  4. 能力模式 - 工具集成

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

故障排查

IssueCauseSolution
Skill not triggeringMissing trigger keywordsAdd trigger phrases to description field
YAML parse errorColon in descriptionReplace colons with dashes in description
Skill not foundWrong locationPlace in 
~/.claude/skills/
or project 
.claude/skills/
validate script failsInvalid frontmatterCheck name format (lowercase-hyphen only)
Resources not loadingWrong path in SKILL.mdUse relative paths from skill directory
Script execution failsMissing shebang or permissionsAdd 
#!/usr/bin/env python3
and 
chmod +x
allowed-tools ignoredAPI skill (not CLI)allowed-tools only works in CLI skills
Description too longOver 1024 charsShorten 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主体