Skip to content

Creating Custom Skills

Josemalyson Oliveira edited this page Jun 27, 2026 · 1 revision

Creating Custom Skills

Learn how to create your own skills for the Custom Skills collection.


Skill Structure

Every skill follows this structure:

skill-name/
├── SKILL.md                    # Main definition
├── references/                 # Supporting documents
│   ├── reference-1.md
│   └── reference-2.md
└── templates/                  # Ready-to-use starting points (optional)
    └── template.html

SKILL.md Template

---
name: skill-name
description: >
  Trigger phrases that activate this skill.
  Be specific about when it should activate.
  Use multiple phrases separated by commas.
---

# Skill Name

## Overview

What this skill does and why it exists.

## When to Use

- Use case 1
- Use case 2
- Use case 3

## Trigger Phrases

- "Phrase 1"
- "Phrase 2"
- "Phrase 3"

## Workflow

### Phase 1: Name

**Objective:** What this phase achieves

**Steps:**
1. Step 1
2. Step 2
3. Step 3

### Phase 2: Name

**Objective:** What this phase achieves

**Steps:**
1. Step 1
2. Step 2
3. Step 3

## Output

What the skill produces.

## References

- `references/file.md` — Description

YAML Frontmatter

The frontmatter defines how the skill is discovered and activated:

---
name: my-skill
description: >
  This is the trigger text.
  The agent reads this to know when to activate.
---

Best Practices

  • Be specific — "Compare X approaches" is better than "help me"
  • Use natural language — Match how users actually ask
  • Include multiple phrases — Cover variations
  • Avoid ambiguity — Don't overlap with other skills

References

Reference documents provide on-demand knowledge for the skill:

Structure

# Reference Title

## Section 1

Content...

## Section 2

Content...

## Examples

```code
example code

### Best Practices

- **Clear titles** — Know what you're looking at
- **Structured content** — Use headings, lists, tables
- **Code examples** — Show, don't just tell
- **Cross-references** — Link to other documents

---

## Templates

Templates provide ready-to-use starting points:

### HTML Templates

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Template</title>
  <style>
    /* CSS here */
  </style>
</head>
<body>
  <!-- Content here -->
  <script>
    // JS here
  </script>
</body>
</html>

Bash Templates

#!/usr/bin/env bash
set -euo pipefail

# Configuration
CONFIG_VAR="${CONFIG_VAR:-default}"

# Functions
function main() {
  echo "Starting..."
  # Main logic
}

function cleanup() {
  echo "Cleaning up..."
}

# Trap
trap cleanup EXIT

# Run
main "$@"

Testing Your Skill

Before submitting:

  1. Test trigger phrases — Verify the skill activates
  2. Test workflow — Follow all phases
  3. Test output — Verify the output is correct
  4. Test edge cases — What happens with invalid input?

Submitting Your Skill

1. Fork & Clone

git clone https://github.com/josemalyson/custom-skills.git
cd custom-skills

2. Create Your Skill

mkdir my-skill
# Create SKILL.md, references/, templates/

3. Update README

Add your skill to:

  • Skills Overview table
  • Project Structure tree

4. Submit PR

  • Use the PR template
  • Include checklist
  • Reference related issues

Style Guidelines

Markdown

  • Use clear headings (H1 for title, H2 for sections)
  • Include code blocks with language tags
  • Use tables for structured data
  • Keep lines under 100 characters

Code

  • Follow existing code style
  • Add comments for complex logic
  • Use meaningful names

References

  • Structure with clear sections
  • Include examples and anti-patterns
  • Cross-reference other documents

Examples

See existing skills for reference:


Last updated: June 2026

Clone this wiki locally