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:

Edit SKILL.md to add instructions and examples
Add detailed docs to references/ if needed
Add helper scripts to scripts/ if applicable
Test the skill in actual usage
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