AgentSkillsCN

opence-skill-creator

学习如何遵循开放性规范，打造高效的项目技能。

SKILL.md
--- frontmatter
name: opence-skill-creator
description: Learn how to create effective project skills following opence conventions.
metadata:
  short-description: Learn skill creation conventions.
<!-- OPENCE:START -->

opence-skill-creator

Learn how to create effective project skills following opence conventions.

When to Create a Skill

Create a skill during the compound phase when you identify:

  • •Repeatable workflows that can be encoded as instructions
  • •Recurring pitfalls or manual checks that need documentation
  • •Domain-specific knowledge that will be useful in future changes

Don't create a skill for one-off solutions or highly specific edge cases.

Quick Start

Use the CLI to create skills (recommended):

bash
# Create a new skill
opence skill add api-testing --description "Guidelines for testing API endpoints"

# List all skills
opence skill list

# Show skill details
opence skill show api-testing

The CLI automatically:

  • •Creates proper directory structure
  • •Generates correct frontmatter for each tool
  • •Validates naming conventions
  • •Creates references/ and scripts/ directories

Skill Structure

code
.claude/skills/my-skill/
├── SKILL.md           # Concise entry point (< 200 lines)
├── references/        # Detailed documentation
│   └── *.md          # Extended guides, examples
└── scripts/          # Reusable code
    └── *.sh, *.py    # Helper scripts

SKILL.md: Keep concise. Include "When to use", key steps, and pointers to references/.

references/: Put detailed docs, long examples, API references here.

scripts/: Add reusable code that users can copy or execute.

Naming Rules

  • •Format: kebab-case (e.g., api-testing, deploy-prod)
  • •Reserved: Don't use opence- prefix (reserved for native skills)
  • •Unique: Check with opence skill list to avoid duplicates

Valid: api-testing, error-recovery, db-migration Invalid: api testing (spaces), api_testing (underscores), opence-custom (reserved)

Writing Effective Descriptions

The description field determines when Claude automatically loads your skill. Write it carefully.

Good description patterns:

  • •Start with an action verb: Explains, Creates, Reviews, Validates, Deploys, Fixes
  • •Include keywords users naturally say
  • •List specific trigger scenarios
  • •Be specific but not overly narrow

Examples of good descriptions:

code
"Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks 'how does this work?'"

"Fix a GitHub issue following our coding standards. Use when working on issues or bugs."

"Research a topic thoroughly using multiple sources. Use for deep dives or comprehensive analysis."

Anti-patterns to avoid:

  • •Too abstract: "Helps with development tasks" — Claude can't decide when to use it
  • •Too specific: "Fix the login button CSS on mobile Safari 15.4" — Won't match future requests
  • •Missing scenarios: "API testing utility" — No trigger context

Trigger phrase checklist:

  • • Does it include words users would naturally say?
  • • Would Claude know when to load it automatically?
  • • Is it distinct from other skills' triggers?

Next Steps

After creating a skill:

  1. •Edit SKILL.md to add instructions and examples
  2. •Add detailed docs to references/ if needed
  3. •Add helper scripts to scripts/ if applicable
  4. •Test the skill in actual usage
  5. •Commit to version control

See references/ for detailed guidance on:

  • •Skill evaluation checklist — Four-question framework and "is it worth creating" criteria
  • •Directory structure and sizing
  • •Frontmatter formats for different tools
  • •Best practices and anti-patterns
<!-- OPENCE:END -->