Skill跨平台适配：五端兼容实战

graph TB
    subgraph "Agent Skills Open Standard"
        A[SKILL.md 文件夹] --> B[YAML Frontmatter]
        A --> C[Markdown 指令体]
    end

    subgraph "五端运行时"
        B --> D[Claude Code]
        B --> E[Cursor]
        B --> F[Gemini CLI]
        B --> G[Codex CLI]
        B --> H[Copilot]
    end

    C --> D
    C --> E
    C --> F
    C --> G
    C --> H

    style A fill:#f9f,stroke:#333
    style D fill:#7cf,stroke:#333
    style E fill:#7cf,stroke:#333
    style F fill:#7cf,stroke:#333
    style G fill:#7cf,stroke:#333
    style H fill:#7cf,stroke:#333

# Claude Code（全局）
~/.claude/skills/my-skill/SKILL.md

# Claude Code（项目级）
.claude/skills/my-skill/SKILL.md

# Cursor（项目级）
.cursor/skills/my-skill/SKILL.md

# Gemini CLI（全局）
~/.gemini/skills/my-skill/SKILL.md

# Gemini CLI（项目级）
.gemini/skills/my-skill/SKILL.md

# Codex CLI（项目级）
.codex/skills/my-skill/SKILL.md

# GitHub Copilot（项目级）
.github/skills/my-skill/SKILL.md

#!/bin/bash
# install-skill-everywhere.sh
# 用法: ./install-skill-everywhere.sh ./my-skill

SKILL_PATH="${1:-./my-skill}"
SKILL_NAME=$(basename "$SKILL_PATH")

# Claude Code 项目级
mkdir -p .claude/skills
cp -r "$SKILL_PATH" .claude/skills/"$SKILL_NAME"

# Cursor 项目级
mkdir -p .cursor/skills
cp -r "$SKILL_PATH" .cursor/skills/"$SKILL_NAME"

# Gemini CLI 项目级
mkdir -p .gemini/skills
cp -r "$SKILL_PATH" .gemini/skills/"$SKILL_NAME"

# Codex CLI 项目级
mkdir -p .codex/skills
cp -r "$SKILL_PATH" .codex/skills/"$SKILL_NAME"

# GitHub Copilot 项目级
mkdir -p .github/skills
cp -r "$SKILL_PATH" .github/skills/"$SKILL_NAME"

echo "✅ $SKILL_NAME installed to all 5 platforms"
ls -la .claude/skills/"$SKILL_NAME"/SKILL.md \
       .cursor/skills/"$SKILL_NAME"/SKILL.md \
       .gemini/skills/"$SKILL_NAME"/SKILL.md \
       .codex/skills/"$SKILL_NAME"/SKILL.md \
       .github/skills/"$SKILL_NAME"/SKILL.md

# 用符号链接（单一来源，修改一处即全部生效）
ln -s "$(pwd)/$SKILL_PATH" .claude/skills/"$SKILL_NAME"
ln -s "$(pwd)/$SKILL_PATH" .cursor/skills/"$SKILL_NAME"
# ... 其他平台同理

---
name: commit-conventional
description: >
  Generate Conventional Commits style commit messages.
  Analyzes staged changes and produces structured commit output.
  Triggered by /commit or when user asks to commit.
---

# Commit Conventional Skill

## Instructions

...（指令体）

---
name: api-tester
description: Run API tests and validate responses against schemas.
trigger: When user mentions API testing, endpoint validation, or schema checking.
allowed-tools: Bash, Read, WebFetch
---

# API Tester Skill
...

<!-- ❌ Cursor 和 Codex 可能无法正确解析 -->
<details>
<summary>Click to expand</summary>
Content here
</details>

<!-- ✅ 使用纯 Markdown -->
**Details**: Content here

<!-- ❌ 只在 Claude Code 有效 -->
Read the file at ~/.claude/settings.json to check permissions.

<!-- ✅ 使用参数化路径 -->
Read the tool's settings file (e.g., ~/.claude/settings.json for Claude Code,
~/.cursor/settings.json for Cursor) to check permissions.

<!-- ❌ 只有 Claude Code 有 Skill tool -->
Invoke the "skill-creator" skill to generate a new skill.

<!-- ✅ 使用条件分支 -->
If using Claude Code: invoke the "skill-creator" skill.
If using Cursor: use @skill-creator in chat.
If using Gemini CLI: use the /skill-creator command.
Otherwise: follow the manual steps below.

## Tool Usage Guidelines

### File Reading
- Claude Code / Gemini CLI: Use the `Read` tool
- Cursor: Use `@file` reference or Read tool
- Codex CLI: Use the built-in file reader

### Command Execution
- Claude Code: Use the `Bash` tool
- Cursor: Use the terminal tool
- Codex CLI: Use shell execution

### Web Access
- Claude Code: Use `WebFetch` or `WebSearch`
- Cursor: Use browser tool
- Gemini CLI: Use Google Search tool

## Step 1: Read Configuration

Read the project's package.json file using your available file reading capability.
Extract the "scripts" section and list all available npm scripts.

graph LR
    subgraph "用户输入"
        U[User Message]
    end

    subgraph "Claude Code"
        U --> C1["/skill-name"]
        U --> C2["Auto-trigger via description match"]
    end

    subgraph "Cursor"
        U --> CR1["@skill-name in chat"]
        U --> CR2["Auto-trigger in Agent mode"]
    end

    subgraph "Gemini CLI"
        U --> G1["/skill-name"]
        U --> G2["Auto-trigger via description"]
    end

    subgraph "Codex CLI"
        U --> CX1["Auto-load on session start"]
        U --> CX2["Auto-trigger via description"]
    end

    subgraph "Copilot"
        U --> CP1["#skill-name in chat"]
        U --> CP2["Auto-trigger via description"]
    end

# ❌ 描述太宽泛，容易误触发
description: Help with Git operations.

# ❌ 描述太窄，用户换一种说法就触发不了
description: Generate conventional commits from git diff --cached output.

# ✅ 平衡具体性与覆盖面
description: >
  Generate structured commit messages following Conventional Commits specification.
  Triggered when user mentions: commit, commit message, conventional commit,
  write commit, generate commit, commit changes.

mkdir -p skills/code-review

---
name: code-review
description: >
  Perform structured code review on current branch changes versus main branch.
  Analyzes security vulnerabilities, performance issues, and maintainability.
  Triggered when user mentions: code review, review code, review PR,
  check my code, audit changes, review changes.
---

# Code Review Skill

## Context

You are a senior code reviewer. Analyze the changes on the current Git branch
compared to the main branch and produce a structured review report.

## Steps

### Step 1: Gather Changes

Run the following command to get the diff:

```bash
git diff main...HEAD --stat

git diff main...HEAD

# Code Review Report

## Summary
- **Branch**: [branch name]
- **Files changed**: [count]
- **Lines added**: [count] | **Lines removed**: [count]
- **Overall assessment**: [APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION]

## Findings

### 🔴 Security Issues ([count])
| # | File | Line | Issue | Severity |
|---|------|------|-------|----------|
| 1 | ... | ... | ... | Critical |

### 🟡 Performance Concerns ([count])
| # | File | Issue | Impact |
|---|------|-------|--------|
| 1 | ... | ... | Medium |

### 🔵 Maintainability Notes ([count])
| # | File | Suggestion | Priority |
|---|------|------------|----------|
| 1 | ... | ... | Low |

## Recommended Actions
1. [Most critical action]
2. [Second priority]
3. [Third priority]

## Positive Highlights
- [Something done well in the changes]

### 6.4 安装到三个平台

```bash
# 一次性复制到三个平台
for dir in .claude .cursor .gemini; do
  mkdir -p "$dir/skills"
  cp -r skills/code-review "$dir/skills/"
done

# 验证安装
find . -path "*/skills/code-review/SKILL.md" -exec echo "✅ {}" \;

✅ .claude/skills/code-review/SKILL.md
✅ .cursor/skills/code-review/SKILL.md
✅ .gemini/skills/code-review/SKILL.md

flowchart TD
    A[Skill 不触发] --> B{检查平台}
    B -->|Claude Code| C["验证 .claude/skills/ 路径"]
    B -->|Cursor| D["验证 .cursor/skills/ 路径<br>确认 Agent 模式开启"]
    B -->|Gemini CLI| E["验证 .gemini/skills/ 路径<br>确认 Skill 被识别"]

    C --> F{frontmatter 格式正确?}
    D --> F
    E --> F

    F -->|No| G["修复 YAML 语法<br>检查缩进和引号"]
    F -->|Yes| H{description 匹配?}

    H -->|No| I["扩展 description 关键词"]
    H -->|Yes| J["检查 Skill 是否冲突<br>查看同名 Skill"]

    G --> K[重新加载]
    I --> K
    J --> K

    K --> L[✅ 验证触发]

# 查看 Claude Code 识别到的所有 Skills
claude /skills

# 验证 Skill 文件格式
cat .claude/skills/code-review/SKILL.md | head -20

# 列出已安装的 Skills
gemini /skills

# 验证路径
ls -la .gemini/skills/*/SKILL.md

# ❌ 错误：description 中有未转义的冒号
description: Generate commit messages: conventional format.

# ✅ 正确：用 > 折叠或引号包裹
description: >
  Generate commit messages following conventional format.

# ❌ 错误：name 包含空格
name: code review

# ✅ 正确：用短横线连接
name: code-review

# ❌ 错误：trigger 是列表格式（某些平台不支持）
trigger:
  - /review
  - review code

# ✅ 正确：用自然语言字符串
trigger: When user mentions code review, review PR, or audit changes.

## Execution Strategy

Detect your current environment and adapt accordingly:

### If running in Claude Code:
- Use the `Bash` tool for all command execution
- Use the `Read` tool for file operations
- Use the `Grep` tool for code search

### If running in Cursor:
- Use the terminal for command execution
- Use the file explorer for reading files
- Use the search panel for code search

### If running in Gemini CLI:
- Use shell execution for commands
- Use the file reading capability for files
- Use Google Search integration for web lookups

### Universal fallback:
- Describe what needs to be done in plain language
- The agent will map to its available tools automatically

---
name: deploy-check
description: >
  Pre-deployment checklist runner. Validates environment configs,
  runs tests, and confirms readiness.
  Triggered by: deploy check, pre-deploy, deployment readiness.
allowed-tools: Bash, Read, Grep, Glob
---

# 仓库结构
team-skills/
├── marketplace.json          # Skill 索引
├── code-review/
│   └── SKILL.md
├── deploy-check/
│   └── SKILL.md
├── api-tester/
│   └── SKILL.md
└── README.md

{
  "name": "Team Skills Registry",
  "skills": [
    {
      "name": "code-review",
      "description": "Structured code review with security, performance, and maintainability analysis",
      "version": "1.2.0",
      "author": "platform-team",
      "tags": ["review", "security", "quality"]
    },
    {
      "name": "deploy-check",
      "description": "Pre-deployment validation checklist",
      "version": "1.0.0",
      "author": "devops-team",
      "tags": ["deploy", "ci", "validation"]
    }
  ]
}

# Claude Code
claude config add-plugin-marketplace https://github.com/your-org/team-skills

# Cursor（通过 settings.json）
# 在 .cursor/settings.json 中添加：
# {
#   "plugins.marketplaces": ["https://github.com/your-org/team-skills"]
# }

# Gemini CLI
# 在 .gemini/settings.json 中添加：
# {
#   "marketplaces": ["https://github.com/your-org/team-skills"]
# }

# .github/workflows/skill-validation.yml
name: Skill Compatibility Check

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate SKILL.md frontmatter
        run: |
          for skill in */SKILL.md; do
            echo "Checking $skill"
            # 检查 YAML frontmatter 是否存在
            head -1 "$skill" | grep -q "^---" || { echo "ERROR: Missing frontmatter in $skill"; exit 1; }
            # 检查必填字段
            grep -q "^name:" "$skill" || { echo "ERROR: Missing 'name' in $skill"; exit 1; }
            grep -q "^description:" "$skill" || { echo "ERROR: Missing 'description' in $skill"; exit 1; }
          done

      - name: Check for platform-specific syntax
        run: |
          # 检测是否包含仅 Claude Code 特有的工具调用
          for skill in */SKILL.md; do
            if grep -q "Use the.*Skill tool" "$skill"; then
              echo "WARNING: $skill contains Claude Code specific syntax"
            fi
          done

---
name: api-docs
description: >
  Generate OpenAPI documentation from code annotations.
  Triggered by: generate API docs, OpenAPI spec, Swagger docs.
---

# API Documentation Generator

## Quick Mode (default)

When user asks for API docs:
1. Scan route/controller files for endpoint definitions
2. Extract HTTP methods, paths, request/response schemas
3. Output a minimal OpenAPI 3.0 spec

## Detailed Mode

When user explicitly requests detailed documentation:
1. Perform Quick Mode steps
2. Add authentication requirements from middleware analysis
3. Generate example requests/responses
4. Add error response schemas
5. Include rate limiting information

## Full Specification Mode

When user requests complete API specification:
1. Perform Detailed Mode steps
2. Add server configurations
3. Generate webhook definitions
4. Include deprecation notices
5. Produce a complete, validatable OpenAPI 3.1 document