Back to Details

skill-check

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Quality Gate

Skill质量检查门

Validate skill quality before deployment. Complements skill-creator (Anthropic's process skill) with specific requirements and quality checks.
Core Principle: Skills encode patterns that Claude needs to apply consistently. The skill should teach Claude HOW to do something, not just WHAT to do.
在部署前验证Skill的质量。补充skill-creator（Anthropic的流程类Skill）的功能，提供特定要求和质量检查。
核心原则： Skills是Claude需要持续应用的模式编码。Skill应教会Claude如何完成任务，而非仅仅告知要做什么。

Relationship with skill-creator

与skill-creator的关系

skill-creator (Anthropic) = PROCESS
  • 6-step workflow: understand → plan → init → edit → package → iterate
  • Template generation and packaging utilities
  • Progressive disclosure principle
skill-quality-gate (this skill) = VALIDATION
  • Naming conventions and requirements
  • Description quality standards with examples
  • Quality checklist before deployment
  • Anti-patterns to avoid
  • Real-world pattern guidance
Use together: Invoke skill-creator for the HOW (process steps), then validate with this skill for the WHAT (quality requirements).
skill-creator（Anthropic）= 流程
  • 6步工作流：理解→规划→初始化→编辑→打包→迭代
  • 模板生成与打包工具
  • 渐进式披露原则
skill-quality-gate（本Skill）= 验证
  • 命名规范与要求
  • 含示例的描述质量标准
  • 部署前的质量检查清单
  • 需避免的反模式
  • 真实场景模式指导
搭配使用： 调用skill-creator获取方法（流程步骤），再通过本Skill验证标准（质量要求）。

When to Use This Skill

何时使用本Skill

Use when:
  • BEFORE writing any SKILL.md file (mandatory gate)
  • After skill-creator generates template (validate before editing)
  • Reviewing skills for quality before deployment
  • Extracting patterns from repeated workflows into codified skills
NOT for:
  • One-off instructions (just put in CLAUDE.md)
  • Simple tool usage (Claude already knows)
  • Tasks that don't repeat across sessions
  • The process steps (use skill-creator for that)
适用场景：
  • 编写任何SKILL.md文件之前（强制检查门）
  • skill-creator生成模板之后（编辑前验证）
  • 部署前审核Skill质量
  • 将重复工作流中的模式提取为可编码的Skill
不适用场景：
  • 一次性指令（直接写入CLAUDE.md即可）
  • 简单工具使用（Claude已掌握）
  • 跨会话不重复的任务
  • 流程步骤相关操作（请使用skill-creator）

Naming Requirements

命名要求

Skill name (YAML frontmatter):
  • Lowercase letters, numbers, hyphens only
  • Max 64 characters
  • Match directory name exactly (critical)
  • Use gerund or capability form: 
    systematic-debugging
    , 
    workspace-fluency
Good names:
  • systematic-debugging
    - clear, action-oriented
  • workspace-fluency
    - describes capability
  • test-driven-development
    - known pattern name
  • desired-outcomes
    - describes the concept
Bad names:
  • pdf-helper
    - vague, "helper" is meaningless
  • utils
    - generic, no information
  • my-skill
    - doesn't describe purpose
  • debug
    - verb, not gerund/capability
Skill名称（YAML前置元数据）：
  • 仅使用小写字母、数字和连字符
  • 最多64个字符
  • 必须与目录名称完全匹配（至关重要）
  • 使用动名词或能力形式：
    systematic-debugging
    、
    workspace-fluency
合格名称示例：
  • systematic-debugging
    - 清晰、面向动作
  • workspace-fluency
    - 描述能力
  • test-driven-development
    - 通用模式名称
  • desired-outcomes
    - 描述核心概念
不合格名称示例：
  • pdf-helper
    - 模糊，“helper”无实际意义
  • utils
    - 过于通用，无有效信息
  • my-skill
    - 未描述用途
  • debug
    - 动词形式，非动名词/能力形式

Description Requirements (CRITICAL)

描述要求（至关重要）

The description is how Claude discovers your skill. This is the most important part.
Pattern for high invocation likelihood:
[ACTION TYPE] + [SPECIFIC TRIGGER] + [METHOD/VALUE PREVIEW]
Best: MANDATORY gate with BEFORE condition
yaml
description: MANDATORY gate before writing any SKILL.md file. Invoke this skill FIRST when building new skills - provides structure template, naming conventions, description requirements, and quality checklist that MUST be validated before deployment.
Why best:
  • "MANDATORY gate" - not optional
  • "before writing" - timing condition
  • "FIRST" - positioning requirement
  • "MUST be validated" - imperative
Good: Specific trigger with method
yaml
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
Why good:
  • Specific trigger: "encountering any bug, test failure"
  • Timing gate: "before proposing fixes"
  • Method preview: "four-phase framework"
  • Value: "ensures understanding before attempting solutions"
Good: Natural phrase triggers
yaml
description: Coach on outcome quality with Tier 2 vs Tier 3 distinction. Triggers on 'check my outcomes', 'is this a good outcome', 'review my Todoist', 'why isn't this working' when discussing strategic work vs tactical projects.
Why good:
  • Explicit trigger phrases in quotes
  • Context qualifier ("when discussing...")
  • Domain-specific terms
Bad: Passive and vague
yaml
description: Helps with debugging code problems
Why bad:
  • No specific trigger
  • Vague ("helps with")
  • No insight into method or timing
Bad: Generic action
yaml
description: Use when creating skills
Why bad:
  • Too generic (I "know" patterns without invoking)
  • No timing gate
  • No method preview
描述是Claude发现你的Skill的关键。这是最重要的部分。
高调用概率的模式：
[动作类型] + [特定触发条件] + [方法/价值预览]
最佳示例：含BEFORE条件的强制检查门
yaml
description: MANDATORY gate before writing any SKILL.md file. Invoke this skill FIRST when building new skills - provides structure template, naming conventions, description requirements, and quality checklist that MUST be validated before deployment.
为何优秀：
  • "MANDATORY gate" - 明确为非可选
  • "before writing" - 明确时间条件
  • "FIRST" - 明确优先级要求
  • "MUST be validated" - 强制语气
良好示例：含方法的特定触发条件
yaml
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
为何优秀：
  • 特定触发条件："encountering any bug, test failure"
  • 时间检查门："before proposing fixes"
  • 方法预览："four-phase framework"
  • 价值体现："ensures understanding before attempting solutions"
良好示例：自然短语触发
yaml
description: Coach on outcome quality with Tier 2 vs Tier 3 distinction. Triggers on 'check my outcomes', 'is this a good outcome', 'review my Todoist', 'why isn't this working' when discussing strategic work vs tactical projects.
为何优秀：
  • 引号标注明确触发短语
  • 上下文限定（"when discussing..."）
  • 领域特定术语
糟糕示例：被动且模糊
yaml
description: Helps with debugging code problems
为何糟糕：
  • 无特定触发条件
  • 模糊表述（"helps with"）
  • 未提及方法或时间
糟糕示例：通用动作
yaml
description: Use when creating skills
为何糟糕：
  • 过于通用（无需加载Claude也“知道”该模式）
  • 无时间检查门
  • 无方法预览

Quality Checklist (MANDATORY)

质量检查清单（强制要求）

Before considering a skill complete, validate ALL items:
在认为Skill完成前，需验证所有项：

Structure

结构

  • SKILL.md under 500 lines
  • Name matches directory name exactly
  • Name is kebab-case, gerund/capability form
  • Description is third-person (verbs: "Orchestrates", "Calibrates", not "Use", "Invoke")
  • Description includes trigger AND method AND timing
  • Description ends with (user) tag for user-defined skills
  • References one level deep from SKILL.md (if used)
  • YAML frontmatter present with name and description
  • SKILL.md不超过500行
  • 名称与目录名称完全匹配
  • 名称为kebab-case格式、动名词/能力形式
  • 描述使用第三人称（动词："Orchestrates"、"Calibrates"，而非"Use"、"Invoke"）
  • 描述包含触发条件、方法和时间要求
  • 用户自定义Skill的描述末尾需加(user)标签
  • SKILL.md的引用最多一级深度（若使用）
  • 含名称和描述的YAML前置元数据

Content

内容

  • No time-sensitive information ("after Aug 2025...")
  • Consistent terminology throughout
  • Concrete examples, not abstract rules
  • Configuration values justified (why these numbers?)
  • Error handling documented
  • Dependencies explicitly listed
  • Anti-patterns section present
  • 无时间敏感信息（例如"after Aug 2025..."）
  • 术语使用一致
  • 提供具体示例，而非抽象规则
  • 配置值有合理说明（为何使用这些数值？）
  • 文档化错误处理方式
  • 明确列出依赖项
  • 包含反模式章节

Workflow

工作流

  • Clear phases/steps with success criteria
  • When to Use AND When NOT to Use sections
  • Integration points with other skills explicit
  • Verification/validation included
  • Quick reference for common operations
  • 含明确阶段/步骤及成功标准
  • 包含何时使用及何时不使用章节
  • 与其他Skill的集成点明确
  • 包含验证/确认环节
  • 常见操作快速参考

Discovery

可发现性

  • Description uses BEFORE/MANDATORY/FIRST patterns where appropriate
  • Trigger phrases are natural language users actually say
  • Context qualifiers included (when appropriate)
  • Method preview gives Claude enough to decide if relevant
  • If paired with a command (
    ~/.claude/commands/*.md
    ), command explicitly names the skill
  • 描述中合理使用BEFORE/MANDATORY/FIRST等模式
  • 触发短语为用户实际会说的自然语言
  • 包含上下文限定词（如适用）
  • 方法预览需为Claude提供足够判断相关性的信息
  • 若与命令（
    ~/.claude/commands/*.md
    ）搭配，命令需明确提及该Skill

Anti-Patterns to Avoid

需避免的反模式

In Discovery (Most Critical)

可发现性相关（最关键）

Anti-PatternProblemFix
"Use when creating..."Too generic, Claude bypasses"MANDATORY gate before...", "Invoke FIRST when..."
"Helps with..."Vague, no specific trigger"Triggers on [phrases]", "Use before [action]"
No timing conditionSkill invocation is optionalAdd BEFORE/FIRST/MANDATORY language
Generic actionsClaude "knows" without loadingSpecific phrases: 'check my outcomes', 'build skill'
Command doesn't name skillLink not discoverable when reviewing"Invoke the 
skill-name
skill" in command
反模式问题修复方案
"Use when creating..."过于通用，Claude会跳过"MANDATORY gate before...", "Invoke FIRST when..."
"Helps with..."模糊，无特定触发条件"Triggers on [phrases]", "Use before [action]"
无时间条件Skill调用为可选操作添加BEFORE/FIRST/MANDATORY等表述
通用动作无需加载Claude也“知道”使用特定短语：'check my outcomes', 'build skill'
命令未提及Skill名称审核时无法发现关联在命令中添加"Invoke the 
skill-name
skill"

In Structure

结构相关

Anti-PatternProblemFix
SKILL.md over 500 linesToken expensiveSplit into references/
Name doesn't match directoryClaude can't find itKeep synchronized
Deeply nested filesDiscovery failsOne level deep max
Missing YAML frontmatterNot discoverableAlways include name and description
反模式问题修复方案
SKILL.md超过500行令牌成本过高拆分至references/目录
名称与目录不匹配Claude无法找到保持名称同步
文件嵌套过深无法被发现最多一级嵌套
缺少YAML前置元数据无法被发现始终包含名称和描述

In Content

内容相关

Anti-PatternProblemFix
Explaining what Claude knowsWastes tokensFocus on domain-specific knowledge
Magic constants without explanationUnclear reasoningJustify all configuration values
Too many options without defaultsAnalysis paralysisProvide recommended path
Mixing terminologyConfusionPick one term, use consistently
反模式问题修复方案
解释Claude已掌握的内容浪费令牌聚焦领域特定知识
无解释的魔法常量推理逻辑不清晰为所有配置值提供说明
选项过多且无默认值导致决策瘫痪提供推荐路径
术语混用造成混淆选定一个术语并保持一致

Integration with Other Skills

与其他Skill的集成

This skill complements:
  • skill-creator - Anthropic's process (template generation, packaging)
  • verification-before-completion - Validate after skill-creator steps
How to reference in your skill:
markdown
undefined
本Skill可补充：
  • skill-creator - Anthropic的流程类Skill（模板生成、打包）
  • verification-before-completion - 在skill-creator步骤完成后验证
在你的Skill中引用的方式：
markdown
undefined

Integration with Other Skills

Integration with Other Skills

Requires:
  • root-cause-tracing - When error is deep in call stack (Phase 1, Step 5)
Complements:
  • verification-before-completion - Verify fix before claiming success
undefined
Requires:
  • root-cause-tracing - When error is deep in call stack (Phase 1, Step 5)
Complements:
  • verification-before-completion - Verify fix before claiming success
undefined

Real-World Skill Quality Patterns

真实场景Skill质量模式

From analyzing Claude Code skills that work well:
通过分析表现优秀的Claude Code Skill总结：

High-Invocation Skills Share

高调用Skill的共性

  1. BEFORE conditions in description (systematic-debugging, verification-before-completion)
  2. Specific trigger phrases in quotes (crash-recovery, desired-outcomes)
  3. Method preview that's actionable (test-driven-development, brainstorming)
  4. Clear anti-patterns that catch mistakes (workspace-fluency)
  5. Integration points that compose (skill referencing skill)
  1. 描述中含BEFORE条件（如systematic-debugging、verification-before-completion）
  2. 引号标注特定触发短语（如crash-recovery、desired-outcomes）
  3. 可落地的方法预览（如test-driven-development、brainstorming）
  4. 明确的反模式（如workspace-fluency）
  5. 可组合的集成点（Skill之间相互引用）

Low-Invocation Skills Suffer From

低调用Skill的问题

  1. Generic "Use when..." descriptions (Claude knows patterns without loading)
  2. Vague value propositions ("helps with", "guides", "assists")
  3. Missing timing gates (no BEFORE/FIRST/MANDATORY)
  4. Documenting what Claude already knows (not teaching new patterns)
  1. 通用的"Use when..."描述（无需加载Claude也知道该模式）
  2. 模糊的价值主张（如"helps with"、"guides"、"assists"）
  3. 缺少时间检查门（无BEFORE/FIRST/MANDATORY表述）
  4. 记录Claude已掌握的内容（未教授新模式）

Common Skill Types

常见Skill类型

Process Skills (like systematic-debugging)

流程类Skill（如systematic-debugging）

  • Iron law or core principle
  • Phases with explicit success criteria
  • Anti-patterns with rationalizations
  • Red flags that trigger "STOP"
  • BEFORE condition in description
  • 铁则或核心原则
  • 含明确成功标准的阶段
  • 带合理解释的反模式
  • 触发“STOP”的危险信号
  • 描述中含BEFORE条件

Fluency Skills (like workspace-fluency)

熟练度类Skill（如workspace-fluency）

  • Tool selection guidance
  • Workflows for common tasks
  • Best practices for domain
  • Error handling patterns
  • Integration with data skills
  • 工具选择指导
  • 常见任务工作流
  • 领域最佳实践
  • 错误处理模式
  • 与数据类Skill集成

Coaching Skills (like desired-outcomes)

指导类Skill（如desired-outcomes）

  • Quality criteria (good vs poor examples)
  • Coaching questions to ask
  • Pattern recognition for bad input
  • Pattern intervention points
  • Specific trigger phrases
  • 质量标准（优秀/糟糕示例）
  • 需提出的指导问题
  • 不良输入的模式识别
  • 模式干预点
  • 特定触发短语

Quality Gate Skills (like this one)

质量检查门类Skill（如本Skill）

  • MANDATORY language in description
  • Checklist-driven validation
  • Requirements with examples
  • Anti-patterns to catch
  • Complement process skills
  • 描述中含MANDATORY表述
  • 基于检查清单的验证
  • 含示例的要求
  • 可识别的反模式
  • 补充流程类Skill

Quick Reference

快速参考

Minimum Viable Skill

最小可用Skill

markdown
---
name: kebab-case-name
description: [TIMING] + [TRIGGER] + [METHOD/VALUE]. Specific phrases: 'phrase1', 'phrase2'.
---
markdown
---
name: kebab-case-name
description: [TIMING] + [TRIGGER] + [METHOD/VALUE]. Specific phrases: 'phrase1', 'phrase2'.
---

Skill Title

Skill Title

[Core principle]
[Core principle]

When to Use

When to Use

[Specific triggers with examples]
[Specific triggers with examples]

When NOT to Use

When NOT to Use

[Clear boundaries]
[Clear boundaries]

Workflow/Process

Workflow/Process

[Steps with success criteria]
[Steps with success criteria]

Anti-Patterns

Anti-Patterns

[What to avoid with fixes]
[What to avoid with fixes]

Quick Reference

Quick Reference

[Common operations]
undefined
[Common operations]
undefined

Files to Include

需包含的文件

FilePurposeWhen Required
SKILL.mdCore instructionsAlways
references/*.mdDetailed guidesWhen >500 lines
scripts/*.pyUtility scriptsWhen deterministic code needed
Use skill-creator to generate this structure automatically.
文件用途何时需要
SKILL.md核心指令始终需要
references/*.md详细指南内容超过500行时
scripts/*.py实用脚本需要确定性代码时
可使用skill-creator自动生成此结构。

Before Sharing

分享前准备

After quality validation, ask: "Are you planning to share this skill/repo publicly?"
If yes, run the sharing scanner:
bash
undefined
质量验证完成后，询问："Are you planning to share this skill/repo publicly?"
若为是，运行分享扫描器：
bash
undefined

Scan for PII, secrets, paths

Scan for PII, secrets, paths

~/.claude/skills/skill-check/scripts/scan.py /path/to/skill
~/.claude/skills/skill-check/scripts/scan.py /path/to/skill

High-risk only (blocking issues)

High-risk only (blocking issues)

~/.claude/skills/skill-check/scripts/scan.py --risk high /path/to/skill
~/.claude/skills/skill-check/scripts/scan.py --risk high /path/to/skill

JSON output for processing

JSON output for processing

~/.claude/skills/skill-check/scripts/scan.py --format json /path/to/skill

**Workflow:**
1. Run scanner on target
2. Triage findings by risk level (high first)
3. Remediate or accept each finding
4. Rescan to verify clean
5. Share

See `references/sharing-scan.md` for detailed triage guidelines.
~/.claude/skills/skill-check/scripts/scan.py --format json /path/to/skill

**工作流：**
1. 对目标运行扫描器
2. 按风险等级分类发现的问题（优先处理高风险）
3. 修复或确认每个问题
4. 重新扫描以确认无问题
5. 分享

详细分类指南请见`references/sharing-scan.md`。

Success Criteria

成功标准

This skill works when:
  • Every skill built passes the quality checklist
  • Description triggers invocation reliably (not bypassed)
  • Naming conventions are consistent across skills
  • Anti-patterns are caught before deployment
  • Integration with skill-creator is smooth
The test: If you find yourself "knowing" skill patterns without formally invoking, the skill's trigger failed. Fix the description.
本Skill生效的标志：
  • 所有构建的Skill均通过质量检查清单
  • 描述能可靠触发调用（不被跳过）
  • 命名规范在所有Skill中保持一致
  • 反模式在部署前被发现
  • 与skill-creator的集成顺畅
测试方法： 若你无需正式调用就能“知道”Skill模式，说明该Skill的触发条件设计失败，请修改描述。

Remember

谨记

Skills must be discovered to be useful. The description is everything.
Process (skill-creator): How to build Validation (skill-making): What quality to meet
Use both. The process without validation produces inconsistent skills. Validation without process is inefficient.
Skill必须能被发现才有用。描述是关键。
流程（skill-creator）： 如何构建 验证（本Skill）： 需达到的质量标准
请搭配使用。无验证的流程会产生不一致的Skill，无流程的验证效率低下。