Skip to main content

Creating Skills

From idea to published skill.

Overview​

┌─────────────────────────────────────────────────────────────┐
│                   SKILL CREATION FLOW                       │
│                                                             │
│   IDEA ──► CREATE ──► WRITE ──► TEST ──► PUBLISH            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Step 1: Create the Skill​

skillshare new my-skill

This creates:

~/.config/skillshare/skills/my-skill/
└── SKILL.md  (with template)

Step 2: Write the Skill​

Edit the generated SKILL.md:

$EDITOR ~/.config/skillshare/skills/my-skill/SKILL.md

Basic structure​

---
name: my-skill
description: Brief description (shown in skill lists)
---

# My Skill

What this skill does and when to use it.

## Instructions

1. Step one
2. Step two
3. Step three

Good skill writing tips​

Be specific:

# Good
When the user asks to review code, analyze for:
- Bugs and potential issues
- Style consistency
- Performance concerns

# Bad
Review the code and make it better.

Include examples:

## Example

User: "Review this function"
```python
def add(a, b):
    return a + b

Response: Suggest adding type hints...


**Specify when NOT to use:**
```markdown
## When NOT to Use

- Don't use for simple syntax questions
- Don't use for explaining code (use explain-code skill instead)

Step 3: Deploy and Test​

Deploy to all targets​

skillshare sync

Test in your AI CLI​

Try using the skill:

  • Invoke explicitly: /skill:my-skill
  • Or describe the task and see if the AI picks it up

Iterate​

Edit → sync → test until it works well.

Step 4: Publish (Optional)​

Share with your team​

Push to your git remote:

skillshare push -m "Add my-skill"

Team members can pull:

skillshare pull

Share publicly​

  1. Create a GitHub repo for your skills
  2. Push your skills directory
  3. Others can install: 
    skillshare install github.com/you/my-skills/my-skill

Skill Templates​

Simple skill​

---
name: simple-skill
description: Does one thing well
---

# Simple Skill

When the user asks to do X, follow these steps:

1. First, do Y
2. Then, do Z
3. Finally, confirm completion

Task-oriented skill​

---
name: code-review
description: Reviews code for quality and issues
---

# Code Review

You are a code reviewer. Analyze code for quality issues.

## What to Check

- Bugs and edge cases
- Performance issues
- Security vulnerabilities
- Code style and readability

## Output Format

For each issue found:
1. **Location**: File and line
2. **Severity**: High/Medium/Low
3. **Issue**: What's wrong
4. **Fix**: Suggested solution

## Example

[Include an example input and expected output]

Process skill​

---
name: git-workflow
description: Guides through git commit workflow
---

# Git Workflow

Guide the user through proper git commit practices.

## Steps

1. **Check status**: Run `git status`
2. **Review changes**: Run `git diff`
3. **Stage files**: Add specific files, not `git add .`
4. **Write message**: Follow conventional commits
5. **Commit**: Create the commit
6. **Verify**: Run `git log -1`

## Commit Message Format

```text
type(scope): description

[optional body]

Types: feat, fix, docs, style, refactor, test, chore

Advanced Topics​

Multiple files in a skill​

A skill can contain additional files:

my-skill/
├── SKILL.md
├── examples/
│   └── sample.py
└── templates/
    └── component.tsx

Reference them in your SKILL.md:

See the example in `examples/sample.py` for reference.

Namespacing for teams​

Avoid collisions with namespaced names:

name: acme:code-review

Version tracking​

Add version metadata:

---
name: my-skill
description: My skill
version: 1.0.0
author: Your Name
---

Checklist​

Before publishing:

  • Clear, specific name
  • Description explains purpose
  • Instructions are actionable
  • Includes examples
  • Tested in AI CLI
  • No conflicts with existing skills