<!-- 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):

# 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

.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:

"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 -->