Claude Code技能定义实战指南：从基础概念到生产环境最佳实践

1次阅读

共计 3077 个字符，预计需要花费 8 分钟才能阅读完成。

刚开始接触 Claude Code 技能开发时，最让人头疼的就是接口规范不统一的问题。同一个团队里，有人用 RESTful 风格，有人用 GraphQL，甚至还有直接裸奔的 JSON-RPC。调试时更痛苦——错误信息像谜语一样，经常要花半天时间猜哪里出了问题。

更糟的是，当多个技能需要组合调用时，你会发现：

参数校验逻辑重复出现在各个 Handler 中
缺乏统一的日志格式，排查问题像大海捞针
并发请求下会出现奇怪的脏数据

可以把 Claude Code 的技能体系想象成一家餐厅：

Skill：相当于整个餐厅的服务范围（比如提供中餐服务）
Action：类似餐厅里的具体菜品（鱼香肉丝、宫保鸡丁等）
Handler：就是后厨做菜的具体步骤（切肉、炒菜、装盘）

和 MVC 架构对比来看：

Action 类似 Controller 层
Handler 相当于 Service 层
内置的 State 管理就是 Model 层

from typing import TypedDict
from claude_sdk import action, validate_input

class RecipeInput(TypedDict):
    ingredients: list[str]
    cook_time: int

@action(name='make_soup')
@validate_input(schema={'ingredients': {'type': 'list', 'required': True},
    'cook_time': {'type': 'integer', 'min': 5}
})
async def soup_handler(input: RecipeInput):
    """制作汤品的处理逻辑"""
    logger.info(f'开始处理汤品，食材: {input["ingredients"]}')

    # 实际烹饪逻辑
    await cook_ingredients(input['ingredients'])
    await simmer(input['cook_time'])

    return {'status': 'done', 'message': '汤品制作完成'}

interface RecipeInput {ingredients: string[];
  cookTime: number;
}

@Action({name: 'makeSoup'})
@ValidateInput({ingredients: { type: 'array', items: { type: 'string'} },
  cookTime: {type: 'number', minimum: 5}
})
async function soupHandler(input: RecipeInput): Promise<Response> {logger.info(` 开始处理汤品，食材: ${input.ingredients.join(',')}`);

  // 实际烹饪逻辑
  await cookIngredients(input.ingredients);
  await simmer(input.cookTime);

  return {status: 'done', message: '汤品制作完成'};
}

乐观锁方案 （适合冲突少的场景）

async def update_recipe(recipe_id: str, version: int, data: dict):
    current = await db.get_recipe(recipe_id)
    if current['version'] != version:
        raise ConflictError('配方已被他人修改')

    await db.update_recipe(recipe_id, {
        **data,
        'version': version + 1
    })

分布式锁方案 （适合强一致性要求）

async function withLock(key: string, callback: () => Promise<void>) {const lock = await redlock.acquire([`lock:${key}`], 5000);
  try {return await callback();
  } finally {await lock.release();
  }
}

预热方案 ：在容器启动时预先加载常用数据
缓存策略 ：对计算结果进行多级缓存

# 使用 LRU 缓存装饰器
@lru_cache(maxsize=128)
async def get_recipe(recipe_id: str):
    return await db.query(...)

异步操作未设置超时
症状：请求永远挂起不返回
修复：为所有外部调用添加 timeout

await asyncio.wait_for(external_api.call(),
    timeout=3.0
)

忽略错误重试机制
症状：偶发失败需要人工重试
修复：实现指数退避重试

async function retryWithBackoff<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
  let lastError: Error;
  for (let i = 0; i < retries; i++) {
    try {return await fn();
    } catch (err) {
      lastError = err;
      await new Promise(r => setTimeout(r, 100 * Math.pow(2, i)));
    }
  }
  throw lastError;
}

日志缺乏关键上下文
症状：看到错误但不知道当时的状态
修复：添加请求链路追踪 ID

logger = logging.getLogger(__name__)
logger = logger.bind(request_id=request.headers.get('X-Request-ID')
)

题目：实现一个智能点餐系统，要求：

组合使用「推荐菜品」「库存检查」「下单」三个 Action
当推荐菜品缺货时自动替换为同类菜品
保证整个流程的原子性（要么全部成功，要么全部回滚）

提示：

使用 Saga 模式管理分布式事务
为每个步骤设计补偿操作
考虑添加断路器防止雪崩

在生产环境中，建议监控以下关键指标：

P99 延迟（反映用户体验）
错误率（稳定性指标）
并发执行数（容量规划依据）

可以这样实现 Prometheus 监控：

from prometheus_client import Summary, Counter

REQUEST_TIME = Summary('request_processing_seconds', 'Time spent processing request')
ERROR_COUNT = Counter('handler_errors_total', 'Total error count by handler')

@REQUEST_TIME.time()
async def handler(input):
    try:
        # 处理逻辑
    except Exception:
        ERROR_COUNT.inc()
        raise

经过多个项目的实践，我总结了 Claude Code 技能开发的三个黄金原则：