SKILL.md规范精解：YAML字段到指令设计全实战

~/.claude/skills/          ← 全局级：所有项目可用
├── code-review/
│   └── SKILL.md
└── security-scan/
    └── SKILL.md

your-project/.claude/skills/   ← 项目级：仅当前项目
├── api-style/
│   └── SKILL.md
└── db-migration/
    └── SKILL.md

your-project/.claude/commands/ ← 自定义命令（旧格式，仍兼容）
├── deploy.md
└── test-all.md

---
name: hello-reviewer
description: A simple code review skill that checks for common issues.
---

# Hello Reviewer

When reviewing code, always check for:
1. Missing error handling
2. Unused imports
3. Hardcoded secrets

# 如果文件路径是 .claude/skills/api-reviewer/SKILL.md
name: api-reviewer    # ✓ 正确：与文件夹名一致
name: api_reviewer    # ✗ 错误：下划线不匹配
name: API-Reviewer    # ✗ 错误：大小写不匹配

# ✗ 差的描述：太模糊
description: A helpful tool for developers.

# ✓ 好的描述：精确的触发条件
description: >
  Use when reviewing Python REST API code for security vulnerabilities.
  Triggers on files matching routes/*.py, views/*.py, or api/*.py.
  Activates for tasks mentioning "API review", "security audit", or "endpoint check".

version: 1.2.0

# 只有用户明确 /skill-name 时才激活
auto-activate: false

disable-model-invocation: true

# 模式一：白名单——只允许指定工具
allowed-tools:
  - Read
  - Grep
  - Glob

# 模式二：黑名单——禁止指定工具
blocked-tools:
  - Bash           # 禁止执行shell命令
  - Write          # 禁止写入文件（只读模式）

# 模式三：混合——允许大部分但排除危险操作
tools:
  - Read
  - Grep
  - Glob
  - Edit
blocked-tools:
  - Bash

variables:
  framework:
    description: Target framework name
    default: react
    type: string
  style-guide:
    description: URL to the team style guide
    type: string
    required: false
  max-complexity:
    description: Maximum cyclomatic complexity allowed
    default: 10
    type: integer

# {{framework}} Code Review

Review all code against the style guide at {{style-guide}}.
Flag any function with cyclomatic complexity > {{max-complexity}}.

input:
  type: object
  properties:
    file_path:
      type: string
      description: Path to the file to review
    severity_threshold:
      type: enum
      values: [low, medium, high, critical]
      default: medium

output:
  type: object
  properties:
    issues:
      type: list
      description: List of found issues
    summary:
      type: string
      description: Brief review summary
    score:
      type: integer
      description: Code quality score (0-100)

hooks:
  pre-invoke:
    - name: validate-project
      description: Ensure the project has the required structure
  post-invoke:
    - name: cleanup-temp-files
      description: Remove temporary files created during skill execution

dependencies:
  skills:
    - name: security-scanner
      version: ">=1.0.0"
    - name: test-runner
  mcp-servers:
    - name: filesystem
    - name: github

metadata:
  author: your-team
  tags: [security, code-review, python]
  license: MIT
  repository: https://github.com/your-org/claude-skills
  min-claude-version: 1.0.25

<!-- ✗ 模糊指令 -->
Review the code and find issues.

<!-- ✓ 锚定指令 -->
## Activation Conditions
Activate this skill ONLY when:
- User explicitly asks for a code review, OR
- The file being edited is in src/api/ directory

DO NOT activate when:
- User is writing tests
- User is making documentation changes

## Review Scope
For each file under review, check:
1. **Error handling**: Every async function must have try/catch
2. **Input validation**: All external inputs must be validated with zod schemas
3. **SQL injection**: Parameterized queries only in database calls

## Review Rules

### MUST (Block on violation)
- [SECURITY] No hardcoded secrets or API keys
- [SECURITY] All user inputs sanitized before database operations
- [CRASH] No unhandled promise rejections in async code

### SHOULD (Warn but don't block)
- [STYLE] Consistent naming conventions per file
- [PERF] Avoid N+1 database queries in loops
- [MAINT] Functions should not exceed 50 lines

### MAY (Suggest as improvement)
- [DX] Consider extracting repeated logic into utility functions
- [TEST] Missing test coverage for edge cases

## Output Format

When reporting issues, use this exact format:

### Example Output

## Constraints (DO NOT)

- DO NOT modify files outside the review scope
- DO NOT add new dependencies without explicit approval
- DO NOT rewrite working code to match personal style preferences
- DO NOT suggest changes that would break existing tests
- DO NOT output more than 20 issues per file (prioritize by severity)

variables:
  severity-threshold:
    type: enum
    values: [info, warn, error, critical]
    default: warn
    description: Minimum severity level to report
  max-issues-per-file:
    type: integer
    default: 20
    description: Maximum number of issues to report per file
  ignore-patterns:
    type: list
    default: ["*.test.ts", "*.spec.ts", "**/generated/**"]
    description: File patterns to exclude from review

## Configuration
- Report severity: {{severity-threshold}} and above
- Max issues per file: {{max-issues-per-file}}
- Skip files matching: {{ignore-patterns}}

~/.claude/skills/api-security-reviewer/
├── SKILL.md           # 主文件
└── references/
    └── owasp-top10.md  # 参考资料（可选）

---
name: api-security-reviewer
description: >
  Activate when reviewing API endpoint code for security vulnerabilities.
  Triggers on files in routes/, controllers/, api/, endpoints/ directories.
  Keywords: "security review", "API audit", "vulnerability scan", "pen test".
version: 1.0.0
auto-activate: true
allowed-tools:
  - Read
  - Grep
  - Glob
  - Edit
blocked-tools:
  - Bash
variables:
  language:
    description: Primary programming language of the API
    type: enum
    values: [typescript, python, go, java]
    default: typescript
  framework:
    description: Web framework being used
    type: string
    default: express
  severity-floor:
    description: Minimum severity level to report
    type: enum
    values: [info, low, medium, high, critical]
    default: medium
  report-format:
    description: Output format for findings
    type: enum
    values: [table, markdown, json]
    default: markdown
metadata:
  author: security-team
  tags: [security, api, owasp, review]
  license: MIT
---

# API Security Reviewer

## Activation Conditions

Activate this skill ONLY when:
- User explicitly requests a security review of API code
- User is editing files in routes/, controllers/, api/, or endpoints/ directories
- User mentions "security", "vulnerability", "OWASP", or "penetration test"

DO NOT activate when:
- User is writing frontend code
- User is modifying configuration files (docker-compose, CI/CD)
- User is working on documentation

## Review Checklist

### MUST Check (Block on finding)
1. **Injection (OWASP A03)**: All database queries use parameterized statements
2. **Authentication (OWASP A07)**: Every endpoint validates auth token before processing
3. **Access Control (OWASP A01)**: Role-based checks present for sensitive operations
4. **Input Validation**: Request body/params validated with schema (zod/joi/pydantic)

### SHOULD Check (Warn on finding)
5. **Rate Limiting**: Endpoints have appropriate rate limiting configured
6. **CORS**: Cross-origin headers are restrictive, not using wildcard `*`
7. **Error Handling**: Error responses don't leak stack traces or internal details
8. **Logging**: Security-relevant events are logged (auth failures, access denied)

### MAY Check (Suggest if time permits)
9. **HTTPS Enforcement**: API only accessible over HTTPS
10. **Response Headers**: Security headers present (X-Content-Type-Options, etc.)

## Language-Specific Rules

{{#if (eq language "typescript")}}
- Check for `any` type casts in request handlers
- Verify `express.json()` has size limits: `express.json({ limit: '10kb' })`
- Ensure `helmet` middleware is configured
{{/if}}

{{#if (eq language "python")}}
- Verify SQLAlchemy uses `text()` with parameters, not f-strings
- Check Flask/Django decorators for `@login_required` or `@permission_required`
- Ensure `CORS` configuration is restrictive
{{/if}}

{{#if (eq language "go")}}
- Check `sql.Query` uses `$1, $2` placeholders, not `fmt.Sprintf`
- Verify `jwt` token validation middleware is applied
- Ensure `http.Error` doesn't expose internal details
{{/if}}

## Output Format

{{#if (eq report-format "markdown")}}
### Example Output

{{/if}}

## Constraints (DO NOT)
- DO NOT modify production configuration files
- DO NOT add new npm/pip packages (only suggest)
- DO NOT write fixes automatically — present findings and let user decide
- DO NOT report issues below severity level: {{severity-floor}}
- DO NOT skip endpoints marked with `@skip-security-review` comment

## Severity Definitions
- **CRITICAL**: Exploitable remotely, no authentication required
- **HIGH**: Exploitable with valid user credentials
- **MEDIUM**: Requires specific conditions or internal access
- **LOW**: Best practice violation, limited attack surface
- **INFO**: Informational, no direct security impact

# 创建目录结构
mkdir -p your-project/.claude/skills/api-security-reviewer

# 将上面的SKILL.md内容写入文件
# 方式一：直接复制
cp SKILL.md your-project/.claude/skills/api-security-reviewer/

# 方式二：通过curl从远程仓库安装
mkdir -p your-project/.claude/skills
curl -sL https://example.com/skills/api-security-reviewer.tar.gz | tar xz -C your-project/.claude/skills/

# 在Claude Code中执行
claude

# 使用斜杠命令触发
/api-security-reviewer

# 或者让Claude自动检测
# 打开一个routes/目录下的文件，输入 "review this API endpoint for security issues"

/api-security-reviewer language=python severity-floor=high

graph TB
    A[Skill测试金字塔] --> B[Layer 1: 加载验证]
    A --> C[Layer 2: 触发测试]
    A --> D[Layer 3: 行为验证]

    B --> B1[SKILL.md语法检查]
    B --> B2[文件夹名与name字段一致]
    B --> B3[YAML字段完整性]

    C --> C1[关键词触发测试]
    C --> C2[文件路径触发测试]
    C --> C3[显式命令触发测试]

    D --> D1[输出格式合规性]
    D --> D2[工具权限遵守]
    D --> D3[否定约束验证]

# 检查Skill是否被Claude Code识别
claude --list-skills

# 手动验证YAML语法
python3 -c "
import yaml, sys
with open('.claude/skills/api-security-reviewer/SKILL.md') as f:
    content = f.read()
    parts = content.split('---')
    if len(parts) < 3:
        sys.exit('Missing YAML frontmatter')
    frontmatter = yaml.safe_load(parts[1])
    assert 'name' in frontmatter, 'Missing name field'
    assert 'description' in frontmatter, 'Missing description field'
    print('✓ YAML frontmatter valid')
    print(f'  name: {frontmatter[\"name\"]}')
    print(f'  description: {frontmatter[\"description\"][:50]}...')
"

# 创建测试用例
cat > /tmp/test-api-route.ts << 'EOF'
import express from 'express';
const router = express.Router();

// This endpoint has intentional security issues for testing
router.post('/users', async (req, res) => {
  const { name, email } = req.body;
  const result = await db.query(
    `SELECT * FROM users WHERE email = '${email}'`
  );
  res.json(result);
});
EOF

# 在Claude Code中测试
claude
> Review /tmp/test-api-route.ts for security issues
# 预期：api-security-reviewer Skill被自动激活

graph LR
    A[Skill开发完成] --> B{分发方式}
    B --> C[npm包]
    B --> D[Git仓库]
    B --> E[插件市场]

    C --> F[npm publish]
    C --> G[团队npm install]

    D --> H[Git submodule]
    D --> I[install脚本]

    E --> J[Plugin Marketplace]
    E --> K[一键安装]

// package.json
{
  "name": "@your-org/claude-skill-security",
  "version": "1.0.0",
  "files": [".claude/skills/**/SKILL.md"],
  "keywords": ["claude-code", "skill", "security"],
  "scripts": {
    "postinstall": "node scripts/install-skills.js"
  }
}

// scripts/install-skills.js
const fs = require('fs');
const path = require('path');

const source = path.join(__dirname, '..', '.claude', 'skills');
const target = path.join(process.cwd(), '.claude', 'skills');

if (!fs.existsSync(target)) {
  fs.mkdirSync(target, { recursive: true });
}

fs.cpSync(source, target, { recursive: true });
console.log('✓ Skills installed to .claude/skills/');

npm install @your-org/claude-skill-security

# 方式A：Git Submodule
git submodule add https://github.com/your-org/claude-skills.git .claude/skills-shared
ln -s .claude/skills-shared/api-security-reviewer .claude/skills/api-security-reviewer

# 方式B：curl一键安装
mkdir -p .claude/skills
curl -sL https://raw.githubusercontent.com/your-org/claude-skills/main/install.sh | bash

# 发布到市场
claude plugin publish --skill api-security-reviewer

# 从市场安装
claude plugin install api-security-reviewer

# 搜索市场
claude plugin search "security review"

flowchart TD
    A[需求分析] --> B[确定触发条件]
    B --> C[编写YAML frontmatter]
    C --> D[编写指令正文]
    D --> E[本地测试]
    E --> F{测试通过?}
    F -->|否| G[调试修复]
    G --> D
    F -->|是| H[团队Review]
    H --> I{Review通过?}
    I -->|否| J[根据反馈修改]
    J --> D
    I -->|是| K[选择分发方式]
    K --> L[npm / Git / 市场]
    L --> M[版本管理与迭代]

    style A fill:#4A90D9,color:#fff
    style E fill:#F5A623,color:#fff
    style K fill:#7ED321,color:#fff
    style M fill:#BD10E0,color:#fff

# .claude/skills/full-audit/SKILL.md
dependencies:
  skills:
    - name: api-security-reviewer
      version: ">=1.0.0"
    - name: performance-analyzer

## Execution Flow
1. Run `api-security-reviewer` first
2. Collect security findings
3. Run `performance-analyzer` next
4. Merge results into unified audit report

variables:
  environment:
    type: enum
    values: [development, staging, production]
    default: development

{{#if (eq environment "production")}}
## Production-Specific Rules
- ALL endpoints must have authentication
- ALL database queries must use connection pooling
- ALL responses must have security headers
{{else}}
## Development Relaxations
- Authentication may be optional for health check endpoints
- Detailed error messages are acceptable
{{/if}}

.claude/skills/
├── _registry.md       # Skill注册表（谁维护、最后更新时间）
├── api-security/
│   └── SKILL.md
├── code-style/
│   └── SKILL.md
└── test-coverage/
    └── SKILL.md

# Team Skill Registry

| Skill | Owner | Last Updated | Status | Version |
|-------|-------|-------------|--------|---------|
| api-security | @security-team | 2026-05-20 | Active | 1.2.0 |
| code-style | @frontend-team | 2026-05-15 | Active | 2.0.1 |
| test-coverage | @qa-team | 2026-05-10 | Beta | 0.3.0 |