跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

creating-skills

Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples

AgentWorkforce · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add AgentWorkforce/relay --skill creating-skills

技能说明


name: creating-skills description: Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples

Creating Skills

Overview

Skills are reference guides for proven techniques, patterns, or tools. Write them to help future Claude instances quickly find and apply effective approaches.

Skills must be discoverable (Claude can find them), scannable (quick to evaluate), and actionable (clear examples).

Core principle: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.

When to Use

Create a skill when:

  • Technique wasn't intuitively obvious
  • Pattern applies broadly across projects
  • You'd reference this again
  • Others would benefit

Don't create for:

  • One-off solutions specific to single project
  • Standard practices well-documented elsewhere
  • Project conventions (put those in .claude/CLAUDE.md)

Required Structure

Frontmatter (YAML)

---
name: skill-name-with-hyphens
description: Use when [triggers/symptoms] - [what it does and how it helps]
tags: relevant-tags
---

Rules:

  • Only name and description fields supported (max 1024 chars total)
  • Name: letters, numbers, hyphens only (max 64 chars). Use gerund form (verb + -ing)
  • Avoid reserved words: "anthropic", "claude" in names
  • Description: Third person, starts with "Use when..." (max 1024 chars)
  • Include BOTH triggering conditions AND what skill does
  • Match specificity to task complexity (degrees of freedom)

Document Structure

# Skill Name

## Overview

Core principle in 1-2 sentences. What is this?

## When to Use

- Bullet list with symptoms and use cases
- When NOT to use

## Quick Reference

Table or bullets for common operations

## Implementation

Inline code for simple patterns
Link to separate file for heavy reference (100+ lines)

## Common Mistakes

What goes wrong + how to fix

## Real-World Impact (optional)

Concrete results from using this technique

Degrees of Freedom

Match specificity to task complexity:

  • High freedom: Flexible tasks requiring judgment

    • Use broad guidance, principles, examples
    • Let Claude adapt approach to context
    • Example: "Use when designing APIs - provides REST principles and patterns"
  • Low freedom: Fragile or critical operations

    • Be explicit about exact steps
    • Include validation checks
    • Example: "Use when deploying to production - follow exact deployment checklist with rollback procedures"

Red flag: If skill tries to constrain Claude too much on creative tasks, reduce specificity. If skill is too vague on critical operations, add explicit steps.

Claude Search Optimization (CSO)

Critical: Future Claude reads the description to decide if skill is relevant. Optimize for discovery.

Description Best Practices

# ❌ BAD - Too vague, doesn't mention when to use
description: For async testing

# ❌ BAD - First person (injected into system prompt)
description: I help you with flaky tests

# ✅ GOOD - Triggers + what it does
description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests

# ✅ GOOD - Technology-specific with explicit trigger
description: Use when using React Router and handling auth redirects - provides patterns for protected routes and auth state management

Keyword Coverage

Use words Claude would search for:

  • Error messages: "ENOENT", "Cannot read property", "Timeout"
  • Symptoms: "flaky", "hanging", "race condition", "memory leak"
  • Synonyms: "cleanup/teardown/afterEach", "timeout/hang/freeze"
  • Tools: Actual command names, library names, file types

Naming Conventions

Use gerund form (verb + -ing):

  • ✅ creating-skills not skill-creation
  • ✅ testing-with-subagents not subagent-testing
  • ✅ debugging-memory-leaks not memory-leak-debugging
  • ✅ processing-pdfs not pdf-processor
  • ✅ analyzing-spreadsheets not spreadsheet-analysis

Why gerunds work:

  • Describes the action you're taking
  • Active and clear
  • Consistent with Anthropic conventions

Avoid:

  • ❌ Vague names like "Helper" or "Utils"
  • ❌ Passive voice constructions

Code Examples

One excellent example beats many mediocre ones.

Choose Language by Use Case

  • Testing techniques → TypeScript/JavaScript
  • System debugging → Shell/Python
  • Data processing → Python
  • API calls → TypeScript/JavaScript

Good Example Checklist

  • Complete and runnable
  • Well-commented explaining WHY not just what
  • From real scenario (not contrived)
  • Shows pattern clearly
  • Ready to adapt (not generic template)
  • Shows both BAD (❌) and GOOD (✅) approaches
  • Includes realistic context/setup code

Example Template

// ✅ GOOD - Clear, complete, ready to adapt
interface RetryOptions {
  maxAttempts: number;
  delayMs: number;
  backoff?: 'linear' | 'exponential';
}

async function retryOperation<T>(operation: () => Promise<T>, options: RetryOptions): Promise<T> {
  const { maxAttempts, delayMs, backoff = 'linear' } = options;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (attempt === maxAttempts) throw error;

      const delay = backoff === 'exponential' ? delayMs * Math.pow(2, attempt - 1) : delayMs * attempt;

      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }

  throw new Error('Unreachable');
}

// Usage
const data = await retryOperation(() => fetchUserData(userId), {
  maxAttempts: 3,
  delayMs: 1000,
  backoff: 'exponential',
});

Don't

  • ❌ Implement in 5+ languages (you're good at porting)
  • ❌ Create fill-in-the-blank templates
  • ❌ Write contrived examples
  • ❌ Show only code without comme
阅读完整来源 ↗