> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with Skills

> Find, install, use, and create skills — on-demand knowledge that teaches Mibyan new workflows

Skills are on-demand knowledge documents that teach Mibyan how to handle specific tasks — from generating ASCII art to managing GitHub PRs. This guide walks you through using them day to day.

For the full technical reference, see [Skills System](/desktop/user-guide/features/skills).

***

## Finding Skills

Every Mibyan installation ships with bundled skills. See what's available:

```bash theme={null}
# In any chat session:
/skills

# Or from the CLI:
mibyan skills list
```

This shows a compact list with names and descriptions:

```
ascii-art         Generate ASCII art using pyfiglet, cowsay, boxes...
arxiv             Search and retrieve academic papers from arXiv...
github-pr-workflow Full PR lifecycle — create branches, commit...
plan              Plan mode — inspect context, write a markdown...
excalidraw        Create hand-drawn style diagrams using Excalidraw...
```

### Searching for a Skill

```bash theme={null}
# Search by keyword
/skills search docker
/skills search music
```

### The Skills Hub

Official optional skills (heavier or niche skills not active by default) are available via the Hub:

```bash theme={null}
# Browse official optional skills
/skills browse

# Search the hub
/skills search blockchain
```

***

## Using a Skill

Every installed skill is automatically a slash command. Just type its name:

```bash theme={null}
# Load a skill and give it a task
/ascii-art Make a banner that says "HELLO WORLD"
/plan Design a REST API for a todo app
/github-pr-workflow Create a PR for the auth refactor

# Just the skill name (no task) loads it and lets you describe what you need
/excalidraw
```

You can also trigger skills through natural conversation — ask Mibyan to use a specific skill, and it will load it via the `skill_view` tool.

### Progressive Disclosure

Skills use a token-efficient loading pattern. The agent doesn't load everything at once:

1. **`skills_list()`** — compact list of all skills (\~3k tokens). Loaded at session start.
2. **`skill_view(name)`** — full SKILL.md content for one skill. Loaded when the agent decides it needs that skill.
3. **`skill_view(name, file_path)`** — a specific reference file within the skill. Only loaded if needed.

This means skills don't cost tokens until they're actually used.

***

## Installing from the Hub

Official optional skills ship with Mibyan but aren't active by default. Install them explicitly:

```bash theme={null}
# Install an official optional skill
mibyan skills install official/research/arxiv

# Install from the hub in a chat session
/skills install official/creative/songwriting-and-ai-music

# Install SKILL.md and its referenced support files from an HTTP(S) URL
mibyan skills install https://sharethis.chat/SKILL.md
/skills install https://example.com/SKILL.md --name my-skill
```

What happens:

1. The skill directory is copied to `~/.mibyan/skills/`
2. It appears in your `skills_list` output
3. It becomes available as a slash command

<Tip>
  Installed skills take effect in new sessions. If you want it available in the current session, use `/reset` to start fresh, or add `--now` to invalidate the prompt cache immediately (costs more tokens on the next turn).
</Tip>

### Verifying Installation

```bash theme={null}
# Check it's there
mibyan skills list | grep arxiv

# Or in chat
/skills search arxiv
```

***

## Plugin-Provided Skills

Plugins can bundle their own skills using namespaced names (`plugin:skill`). This prevents name collisions with built-in skills.

```bash theme={null}
# Load a plugin skill by its qualified name
skill_view("superpowers:writing-plans")

# Built-in skill with the same base name is unaffected
skill_view("writing-plans")
```

Plugin skills are **not** listed in the system prompt and don't appear in `skills_list`. They're opt-in — load them explicitly when you know a plugin provides one. When loaded, the agent sees a banner listing sibling skills from the same plugin.

For how to ship skills in your own plugin, see [Build a Mibyan Plugin → Bundle skills](/desktop/developer-guide/plugins/overview#bundle-skills).

***

## Configuring Skill Settings

Some skills declare configuration they need in their frontmatter:

```yaml theme={null}
metadata:
  mibyan:
    config:
      - key: tenor.api_key
        description: "Tenor API key for GIF search"
        prompt: "Enter your Tenor API key"
        url: "https://developers.google.com/tenor/guides/quickstart"
```

When a skill with config is first loaded, Mibyan prompts you for the values. They're stored in `config.yaml` under `skills.config.*`.

Manage skill config from the CLI:

```bash theme={null}
# Interactive config for a specific skill
mibyan skills config gif-search

# View all skill config
mibyan config get skills.config --json
```

***

## Creating Your Own Skill

Skills are just markdown files with YAML frontmatter. Creating one takes under five minutes.

### 1. Create the Directory

```bash theme={null}
mkdir -p ~/.mibyan/skills/my-category/my-skill
```

### 2. Write SKILL.md

```markdown title="~/.mibyan/skills/my-category/my-skill/SKILL.md" theme={null}
---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
metadata:
  mibyan:
    tags: [my-tag, automation]
    category: my-category
---

# My Skill

## When to Use
Use this skill when the user asks about [specific topic] or needs to [specific task].

## Procedure
1. First, check if [prerequisite] is available
2. Run `command --with-flags`
3. Parse the output and present results

## Pitfalls
- Common failure: [description]. Fix: [solution]
- Watch out for [edge case]

## Verification
Run `check-command` to confirm the result is correct.
```

### 3. Add Reference Files (Optional)

Skills can include supporting files the agent loads on demand:

```
my-skill/
├── SKILL.md                    # Main skill document
├── references/
│   ├── api-docs.md             # API reference the agent can consult
│   └── examples.md             # Example inputs/outputs
├── templates/
│   └── config.yaml             # Template files the agent can use
└── scripts/
    └── setup.sh                # Scripts the agent can execute
```

Reference these in your SKILL.md:

```markdown theme={null}
For API details, load the reference: `skill_view("my-skill", "references/api-docs.md")`
```

### 4. Test It

Start a new session and try your skill:

```bash theme={null}
mibyan chat -q "/my-skill help me with the thing"
```

The skill appears automatically — no registration needed. Drop it in `~/.mibyan/skills/` and it's live.

<Info>
  The agent can also create and update skills itself using `skill_manage`. After solving a complex problem, Mibyan may offer to save the approach as a skill for next time.
</Info>

***

## Per-Platform Skill Management

Control which skills are available on which platforms:

```bash theme={null}
mibyan skills
```

This opens an interactive TUI where you can enable or disable skills per platform (CLI, Telegram, Discord, etc.). Useful when you want certain skills only available in specific contexts — for example, keeping development skills off Telegram.

***

## Skills vs Memory

Both are persistent across sessions, but they serve different purposes:

| | Skills | Memory |
| - | - | - |
| **What** | Procedural knowledge — how to do things | Factual knowledge — what things are |
| **When** | Loaded on demand, only when relevant | Injected into every session automatically |
| **Size** | Can be large (hundreds of lines) | Should be compact (key facts only) |
| **Cost** | Zero tokens until loaded | Small but constant token cost |
| **Examples** | "How to deploy to Kubernetes" | "User prefers dark mode, lives in PST" |
| **Who creates** | You, the agent, or installed from Hub | The agent, based on conversations |

**Rule of thumb:** If you'd put it in a reference document, it's a skill. If you'd put it on a sticky note, it's memory.

***

## Tips

**Keep skills focused.** A skill that tries to cover "all of DevOps" will be too long and too vague. A skill that covers "deploy a Python app to Fly.io" is specific enough to be genuinely useful.

**Let the agent create skills.** After a complex multi-step task, Mibyan will often offer to save the approach as a skill. Say yes — these agent-authored skills capture the exact workflow including pitfalls that were discovered along the way.

**Use categories.** Organize skills into subdirectories (`~/.mibyan/skills/devops/`, `~/.mibyan/skills/research/`, etc.). This keeps the list manageable and helps the agent find relevant skills faster.

**Update skills when they go stale.** If you use a skill and hit issues not covered by it, tell Mibyan to update the skill with what you learned. Skills that aren't maintained become liabilities.

***

*For the complete skills reference — frontmatter fields, conditional activation, external directories, and more — see [Skills System](/desktop/user-guide/features/skills).*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.