Claude-Code-Workflow/docs/zh/skills/custom.md

自定义技能开发

创建和部署自定义 CCW 技能指南。

技能结构

~/.claude/skills/my-skill/
├── SKILL.md          # 技能定义（必需）
├── index.ts          # 技能逻辑（可选）
├── examples/         # 使用示例
└── README.md         # 文档

创建技能

1. 定义技能元数据

创建带 YAML 前言的 SKILL.md：

---
name: my-skill
description: My custom skill for X
version: 1.0.0
author: Your Name <email@example.com>
tags: [custom, automation, frontend]
category: development
---

# My Custom Skill

## What It Does
技能用途和功能的详细描述。

## Usage

\`\`\`javascript
Skill(skill="my-skill", args="your input here")
\`\`\`

## Examples

### Example 1: Basic Usage
\`\`\`javascript
Skill(skill="my-skill", args="create user form")
\`\`\`

### Example 2: With Options
\`\`\`javascript
Skill(skill="my-skill", args={
  component: "UserForm",
  typescript: true,
  styling: "tailwind"
})
\`\`\`

2. 实现技能逻辑（可选）

对于复杂技能，添加 index.ts：

import type { SkillContext, SkillResult } from '@ccw/types'

interface MySkillOptions {
  component?: string
  typescript?: boolean
  styling?: 'css' | 'tailwind' | 'scss'
}

export async function execute(
  args: string | MySkillOptions,
  context: SkillContext
): Promise<SkillResult> {
  // 解析输入
  const options = typeof args === 'string'
    ? { component: args }
    : args

  // 执行技能逻辑
  const result = await generateComponent(options)

  return {
    success: true,
    output: result,
    metadata: {
      skill: 'my-skill',
      version: '1.0.0',
      timestamp: new Date().toISOString()
    }
  }
}

async function generateComponent(options: MySkillOptions) {
  // 你的实现代码
  return `// Generated code`
}

技能类别

开发

• 组件生成器
• API 脚手架
• 数据库模式创建

文档

• API 文档生成
• README 创建
• Changelog 生成

DevOps

• CI/CD 配置
• Dockerfile 生成
• Kubernetes 清单

测试

• 测试生成
• Mock 创建
• 覆盖率报告

技能最佳实践

1. 明确用途

# 好的：清晰和具体
name: generate-react-component
description: 生成带 hooks 和 TypeScript 的 React 组件

# 坏的：模糊和通用
name: code-helper
description: 帮助编码

2. 类型安全

// 定义清晰的接口
interface Options {
  name: string
  typescript?: boolean
  styling?: 'css' | 'tailwind'
}

// 验证输入
function validateOptions(options: any): Options {
  if (!options.name) {
    throw new Error('组件名称是必需的')
  }
  return options as Options
}

3. 错误处理

try {
  const result = await generateComponent(options)
  return { success: true, output: result }
} catch (error) {
  return {
    success: false,
    error: error.message,
    suggestion: '确保组件名称有效'
  }
}

4. 文档

## Usage

\`\`\`javascript
Skill(skill="my-skill", args="...")
\`\`\`

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| name | string | required | 组件名称 |
| typescript | boolean | true | 使用 TypeScript |

## Examples

更多示例参见 `examples/` 目录。

发布技能

私有技能

~/.claude/skills/ 中的技能自动可用。

团队技能

通过 git 共享技能：

# 创建技能仓库
mkdir my-ccw-skills
cd my-ccw-skills
git init

# 添加技能
mkdir skills/skill-1
# ... 添加技能文件

# 与团队共享
git remote add origin <repo-url>
git push -u origin main

团队成员安装：

git clone <repo-url> ~/.claude/skills/team-skills

公共技能

发布到 npm：

{
  "name": "ccw-skills-my-skill",
  "version": "1.0.0",
  "ccw": {
    "skills": ["my-skill"]
  }
}

测试技能

在 tests/ 中创建测试：

import { describe, it, expect } from 'vitest'
import { execute } from '../index'

describe('my-skill', () => {
  it('should generate component', async () => {
    const result = await execute('UserForm', {})
    expect(result.success).toBe(true)
    expect(result.output).toContain('UserForm')
  })
})

调试

启用调试日志：

export CCW_DEBUG=1
ccw skill run my-skill "test input"

::: info 参见

• 核心技能 - 内置技能参考
• 技能库 - 所有可用技能 :::