Creating Skills

🧬 Skill Anatomy

Every OMNISKILL skill lives in its own directory under skills/ and follows this structure:

Step 1: manifest.yaml

The manifest declares everything about your skill except the instructions themselves:

name: my-awesome-skill
version: 1.0.0
description: "What this skill does in one sentence"
author: your-name
license: MIT

platforms: [claude-code, copilot-cli, cursor, windsurf, antigravity]

tags: [domain, category, keywords]

triggers:
  keywords: ["exact phrase 1", "exact phrase 2"]
  patterns: ["pattern with * wildcards"]

priority: P2

Trigger Design Tips

Step 2: SKILL.md

This is the instruction file the AI agent reads. Required sections:

🎭 Identity

Who is this skill? What's its role and personality?

# My Awesome Skill

You are a **specialist** in [domain]. Your role is to [primary function]...

## Core Identity
- Expert in [area]
- Focused on [goals]
- Prioritizes [values]

🎯 When to Use

Trigger conditions, keywords, and anti-patterns (when NOT to use).

## When to Use

Activate this skill when:
- User asks to [scenario 1]
- User mentions [keyword]
- [Specific condition]

Do NOT use this skill when:
- [Anti-pattern 1]
- [Out of scope scenario]

⚙️ Workflow

Step-by-step process the agent follows.

## Workflow

1. **Analyze** — Understand the request
2. **Plan** — Determine approach
3. **Execute** — Perform the task
4. **Validate** — Verify output quality
5. **Document** — Create artifacts

📏 Rules

DO and DON'T lists — guardrails for the agent.

## Rules

### DO:
- Follow best practices for [domain]
- Validate all inputs
- Document decisions

### DON'T:
- Skip validation steps
- Make assumptions about [X]
- Proceed without confirmation

📦 Output Format

What the skill produces, in what format, saved where.

## Output Format

Produce a [type of file] with:
- Section A containing [content]
- Section B containing [content]

Save to: `output/[filename]`

🤝 Handoff

What happens after the skill completes.

## Handoff

After completion:
- Inform user that [artifact] is ready
- Suggest next step: [action]
- If part of pipeline, pass [artifact] to [next agent]

Step 3: Resources (Optional but Recommended)

Add reference materials the agent can consult:

Declare resources in your manifest:

resources:
  - path: resources/cheat-sheet.md
    type: cheat-sheet
    load: always
  - path: resources/style-guide.md
    type: style-guide
    load: on-demand

Step 4: Tests

Add test cases in tests/cases/ to validate your skill:

name: "Basic skill test"
input: "User prompt that should trigger this skill"
expected:
  contains: ["expected output pattern"]
  not_contains: ["things that should NOT be in output"]
  sections: ["required output sections"]

---

name: "Edge case test"
input: "Complex scenario prompt"
expected:
  contains: ["specific behavior"]
  format: "expected file format"

Step 5: Validate

Run the validation script to ensure your skill is well-formed:

$ python scripts/validate.py skills/my-awesome-skill

The validator checks:

• manifest.yaml completeness and schema compliance
• SKILL.md required sections are present
• Trigger uniqueness (no conflicts with other skills)
• Resources exist and are accessible
• Tests are parseable

Step 6: Platform Overrides (Optional)

If your skill needs different behavior on specific platforms:

These are merged with the base SKILL.md during adapter transformation.

# Cursor-Specific Behavior

## Additional Rules for Cursor
- Use Cursor's native file navigation
- Leverage Cursor's inline suggestions
- Output format adjusted for .mdc rules

✨ Best Practices

1. Single Responsibility

Each skill should do one thing exceptionally well. If your skill does multiple unrelated things, split it into separate skills and compose them with a bundle.

2. Clear Triggers

Make triggers specific enough to avoid false positives, but broad enough to be useful. Test your triggers against real user prompts.

3. Comprehensive Resources

Don't rely on the AI's general knowledge for domain-specific facts. Provide cheat sheets, lookup tables, and style guides.

4. Detailed Workflow

The more explicit your workflow, the more consistent the output. Don't skip steps or leave things to interpretation.

5. Robust Testing

Test edge cases, not just happy paths. Your skill will encounter unexpected inputs in the wild.

6. Document Decisions

If your skill makes choices (like selecting a framework or architecture), document the decision-making process in resources.

🤖 Self-Customization Skills

OMNISKILL includes AI-guided skills for creating new skills, bundles, and agents:

The add-skill Skill

Instead of manually following these steps, tell your AI assistant:

The add-skill skill provides:

• Interactive checklist guiding you through each step
• Validation checks at each stage
• Template generation
• Trigger conflict detection
• Automatic validation and installation

Example Advanced Skills

See these skills as examples of advanced patterns:

skills/
├── complexity-router/    # Classifies task complexity and routes 
│                          # to optimal model tier
└── knowledge-sources/    # Integrates external knowledge 
                           # repositories

⚙️ Generator Tool Pattern

For real-time status visualization, use the async generator pattern:

async def process_task():
    yield {"status": "loading", "message": "Initializing..."}
    # Do work
    yield {"status": "processing", "message": "Analyzing code..."}
    # More work
    yield {"status": "done", "result": output}

This pattern enables the AI assistant to show live progress updates. See skills/_template/resources/tool-pattern.md for the full specification.