Skills System - Mibyan Docs

Skills are on-demand knowledge documents the agent can load when needed. They follow a progressive disclosure pattern to minimize token usage and are compatible with the agentskills.io open standard. All skills live in ~/.mibyan/skills/ — the primary directory and source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here. The agent can modify or delete any skill. You can also point Mibyan at external skill directories — additional folders scanned alongside the local one. See External Skill Directories below. See also:

Browse and install in Desktop

Open Capabilities → Skills and switch between Installed and Browse. Search stays at the top; the tab switch and actions share one row. Installed reads the selected profile’s actual skills and enabled state; it is not inferred from the public catalog. Browse is a native catalog UI, not an embedded website or a second, smaller catalog. Desktop and the public Skills Hub read the same published CDN snapshot: /docs/api/skills.json. The public docs alias serves the same snapshot as Desktop’s fetch URL, https://nousresearch.github.io/hermes-agent/docs/api/skills.json. The docs build generates it from bundled skills/, optional-skills/, and the centralized skills index. Browsing does not crawl GitHub or query upstream marketplaces live; installation still retrieves the selected skill through its source’s installer.

Install from the website

The Skills Hub has an Install in Mibyan button on each installable card. It opens the installed Mibyan Desktop app with a URL-encoded, source-qualified skill target: for example, official/... for optional skills or clawhub/... for ClawHub. Bundled skills use an explicit repository path rather than an ambiguous bare name. When an older snapshot lacks that explicit bundled target, the website omits its install link and native Browse disables installation rather than resolving an ambiguous name. The next docs publish supplies those targets. The same target is used by native Browse and the card’s CLI fallback:

mibyan://skill/install?identifier=official%2Fsecurity%2F1password

Mibyan shows Install “skill-name”? with separate Source and Install to rows. Cancel makes no changes. After confirmation, the same dialog shows Installing…, then Installed and a completion notification. Errors stay in the dialog so you can read them and retry. Installation uses the existing Skills Hub pipeline, including security scanning, action logs, and installed-list refresh. If you switch profile or connection while the confirmation is open, reopen the link for the new destination. Changes apply to new sessions; a link cannot bypass scanning or select a different profile. The public links use mibyan://, not the development-only mibyan-dev:// scheme. The skill/install route requires an updated Desktop build. If the app is missing or the link is not recognized, update Desktop or expand the card to copy its CLI install command instead.

Starting with a blank slate

By default every profile is seeded with the bundled skill catalog, and each mibyan update adds any newly bundled skills. If you want a profile with no bundled skills — and that stays empty across updates — you have two paths: At install time (applies to the default ~/.mibyan profile): the installer has no --no-skills flag. Its setup stage asks whether to seed the bundled catalog when you pick the Blank Slate setup; answering no writes the opt-out marker described below. Non-interactive installs seed the catalog, so run mibyan skills opt-out afterwards if you want the profile empty. At profile-create time (named profiles):

mibyan profile create research --no-skills

On an already-installed profile (default or named), toggle it at runtime:

mibyan skills opt-out            # stop future seeding — nothing on disk is touched
mibyan skills opt-out --remove   # also delete UNMODIFIED bundled skills (confirms first)
mibyan skills opt-in --sync      # undo: remove the marker and re-seed now

All of these paths write a .no-bundled-skills marker into the profile directory. While the marker is present, the installer, mibyan update, and any skill sync all skip bundled-skill seeding for that profile. Delete the marker (or run mibyan skills opt-in) to re-enable.

Safe by defaultmibyan skills opt-out only stops future seeding — it never deletes anything already on disk. The optional --remove flag deletes bundled skills only when they are unmodified (byte-identical to the version Mibyan installed). Skills you have edited, skills installed from the hub, and skills you wrote yourself are always kept.

Using Skills

Every installed skill is automatically available as a slash command:

# In the CLI or any messaging platform:
/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/songsee analyze the frequency spread of this mix

# Just the skill name loads it and lets the agent ask what you need:
/excalidraw

Stacking multiple skills in one command

You can invoke several skills in a single message by chaining slash commands at the start — every leading /skill token (up to 5) is loaded, and the rest becomes your instruction:

/github-pr-workflow /test-driven-development fix issue #123 and open a PR

Parsing stops at the first token that isn’t an installed skill, so arguments that happen to start with / (like file paths) are never swallowed:

/ocr-and-documents ~/.mibyan/cache/scratch/scan.pdf extract the tables   # loads one skill; ~/.mibyan/cache/scratch/scan.pdf is the argument

For combinations you use repeatedly, prefer a skill bundle — same effect under one short command. (Plan mode works the same way but is a built-in command now: /plan [request] tells Mibyan to inspect context if needed, write a markdown implementation plan instead of executing the task, and save the result under .mibyan/plans/ relative to the active workspace/backend working directory.) You can also interact with skills through natural conversation:

mibyan chat --toolsets skills -q "What skills do you have?"
mibyan chat --toolsets skills -q "Show me the axolotl skill"

Learning a skill from sources (`/learn`)

/learn is the fast way to turn something you already know — or a pile of reference material — into a reusable skill, without hand-writing the SKILL.md. It is open-ended: point it at anything you can describe and the agent gathers the material with the tools it already has, then authors a skill that follows the house authoring standards (≤60-char description, the standard section order, Mibyan-tool framing, no invented commands).

# A local SDK or doc directory — read with read_file / search_files
/learn the REST client in ~/projects/acme-sdk, focus on auth + pagination

# An online doc page — fetched with web_extract
/learn https://docs.example.com/api/quickstart

# The workflow you just walked the agent through in this conversation
/learn how I just deployed the staging server

# Pasted notes / a described procedure
/learn filing an expense: open the portal, New > Expense, attach the receipt, submit

# A whole book, paper stack, or large docs corpus — becomes a knowledge-base skill
/learn ~/books/designing-data-intensive-applications.pdf

Large sources become knowledge-base skills

When the source is a book, a stack of papers, a spec, or a large docs folder, the agent doesn’t cram it into one file or reduce it to a lossy summary. Instead it authors an expansive knowledge-base skill: a lean SKILL.md carrying the source’s core mental models plus an index, with one distilled file per chapter or topic under references/ (plus a glossary or cheatsheet when the source earns them). Reference files cost nothing until a question needs one — the agent loads them on demand with skill_view, so query cost stays proportional to the answer, not the source. Re-running /learn with new material on the same topic folds it into the existing skill rather than creating a duplicate. The distillation synthesizes structure — frameworks, definitions, decision rules, anti-patterns — and never reproduces passages of the source text. Because the live agent does the sourcing, /learn works the same in the CLI, the messaging gateway, the TUI, and the dashboard — and on any terminal backend (local, Docker, remote), since there is no separate ingestion engine. In the dashboard, the Skills page has a Learn a skill button that opens a panel with a directory field, a URL field, and an open-ended text box; it composes a /learn request and runs it in chat. There is no model-tool footprint: /learn builds a standards-guided prompt and hands it to the agent as a normal turn. The agent saves the result with the skill_manage tool, so the write-approval gate applies if you have it on.

Progressive Disclosure

Skills use a token-efficient loading pattern:

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata       (varies)
Level 2: skill_view(name, path)  → Specific reference file       (varies)

The agent only loads the full skill content when it actually needs it.

SKILL.md Format

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]     # Optional — restrict to specific OS platforms
metadata:
  mibyan:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]    # Optional — conditional activation (see below)
    requires_toolsets: [terminal]   # Optional — conditional activation (see below)
    config:                          # Optional — config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Platform-Specific Skills

Skills can restrict themselves to specific operating systems using the platforms field:

Value	Matches
`macos`	macOS (Darwin)
`linux`	Linux
`windows`	Windows

platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders, FindMy)
platforms: [macos, linux]     # macOS and Linux

When set, the skill is automatically hidden from the system prompt, skills_list(), and slash commands on incompatible platforms. If omitted, the skill loads on all platforms.

Skill output and media delivery

When a skill response (or any agent response) includes a bare absolute path to a media file — for example /home/user/screenshots/diagram.png — the gateway auto-detects it, strips it from the visible text, and delivers the file natively to the user’s chat (Telegram photo, Discord attachment, etc.) instead of leaving the raw path in the message. For audio specifically, the [[audio_as_voice]] directive promotes audio files to native voice-message bubbles on platforms that support them (Telegram, WhatsApp).

Forcing document-style delivery: `[[as_document]]`

Sometimes you want the opposite of inline preview: you want the file delivered as a downloadable attachment, not a re-compressed image bubble. The classic example is a high-resolution screenshot or chart — Telegram’s sendPhoto recompresses it to ~200 KB at 1280 px, destroying readability. A 1-2 MB PNG sent via sendDocument keeps the original bytes intact. If a response (or any text inside it — typically the last line) contains the literal directive [[as_document]], every media path extracted from that response is delivered as a document/file attachment rather than an image bubble:

Here is your rendered chart:

/home/user/.mibyan/cache/chart-q4-2025.png

[[as_document]]

The directive is stripped before delivery, so users never see it. Granularity is intentionally all-or-nothing per response: emit [[as_document]] once and every image path in the same response is delivered as a document. This mirrors the scope of [[audio_as_voice]]. Use it from a skill when:

You produce screenshots or charts the user needs as files (for editing in another tool, archiving, sharing intact).
The default lossy preview would obscure detail (small text, pixel-accurate diagrams, color-sensitive renders).

Platforms without a separate document path (e.g. SMS) fall back to whatever attachment mechanism they have.

Conditional Activation (Fallback Skills)

Skills can automatically show or hide themselves based on which tools are available in the current session. This is most useful for fallback skills — free or local alternatives that should only appear when a premium tool is unavailable.

metadata:
  mibyan:
    fallback_for_toolsets: [web]      # Show ONLY when these toolsets are unavailable
    requires_toolsets: [terminal]     # Show ONLY when these toolsets are available
    fallback_for_tools: [web_search]  # Show ONLY when these specific tools are unavailable
    requires_tools: [terminal]        # Show ONLY when these specific tools are available

Field	Behavior
`fallback_for_toolsets`	Skill is hidden when the listed toolsets are available. Shown when they’re missing.
`fallback_for_tools`	Same, but checks individual tools instead of toolsets.
`requires_toolsets`	Skill is hidden when the listed toolsets are unavailable. Shown when they’re present.
`requires_tools`	Same, but checks individual tools.

Example: The built-in duckduckgo-search skill uses fallback_for_toolsets: [web]. When you have FIRECRAWL_API_KEY set, the web toolset is available and the agent uses web_search — the DuckDuckGo skill stays hidden. If the API key is missing, the web toolset is unavailable and the DuckDuckGo skill automatically appears as a fallback. Skills without any conditional fields behave exactly as before — they’re always shown.

Secure Setup on Load

Skills can declare required environment variables without disappearing from discovery:

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

When a missing value is encountered, Mibyan asks for it securely only when the skill is actually loaded in the local CLI. You can skip setup and keep using the skill. Messaging surfaces never ask for secrets in chat — they tell you to use mibyan setup or ~/.mibyan/.env locally instead. Once set, declared env vars are automatically passed through to execute_code and terminal sandboxes — the skill’s scripts can use $TENOR_API_KEY directly. For non-skill env vars, use the terminal.env_passthrough config option. See Environment Variable Passthrough for details.

Skill Config Settings

Skills can also declare non-secret config settings (paths, preferences) stored in config.yaml:

metadata:
  mibyan:
    config:
      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path

Settings are stored under skills.config in your config.yaml. mibyan config migrate prompts for unconfigured settings, and mibyan config show displays them. When a skill loads, its resolved config values are injected into the context so the agent knows the configured values automatically. See Skill Settings and Creating Skills — Config Settings for details.

Skill Directory Structure

~/.mibyan/skills/                  # Single source of truth
├── mlops/                         # Category directory
│   ├── axolotl/
│   │   ├── SKILL.md               # Main instructions (required)
│   │   ├── references/            # Additional docs
│   │   ├── templates/             # Output formats
│   │   ├── scripts/               # Helper scripts callable from the skill
│   │   ├── examples/              # Referenced example outputs
│   │   └── assets/                # Supplementary files
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/                # Agent-created skill
│       ├── SKILL.md
│       └── references/
├── .hub/                          # Skills Hub state
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest              # Tracks seeded bundled skills

Third-party URL and GitHub installs include SKILL.md plus the exact local files it references under references/, templates/, scripts/, assets/, and examples/. Unreferenced repository files are not copied. Mibyan scans the complete quarantined bundle and records the source URL, exact content hash, scanner version, findings, timestamp, and fresh-or-cached status in skills/.hub/lock.json.

Advisory SkillEvaluator scan

In addition to the built-in security scanner (which enforces the install policy above), Mibyan can run NVIDIA SkillEvaluator Tier 1 checks on every hub install as a second opinion. Tier 1 is deterministic and keyless — PII detection (leaked emails, personal paths, connection strings), unicode-smuggling detection, script lint, license compliance, and a static security scan via NVIDIA SkillSpector. The scan is advisory only: findings are printed with file and line before the install confirmation, and the install continues. Findings that look like real credentials (private keys, cloud access keys, tokens, credentialed connection strings) are highlighted in red so you can review the flagged lines before deciding. PII-class findings are informational — the upstream scanner has known false-positive classes (e.g. git@github.com SSH syntax, documentation example emails), so they never block anything. To enable it, install the optional scanner binaries (the second one powers the security check; without it that check simply reports “not run”):

uv tool install --python 3.13 \
  "skillevaluator @ git+https://github.com/NVIDIA/SkillEvaluator.git@v0.1.0"
uv tool install "git+https://github.com/NVIDIA/SkillSpector.git@v2.9.5"

Without the binary on PATH the scan is silently skipped. To turn it off entirely:

skills:
  tier1_advisory: false

The dashboard’s Browse-hub scan button returns the same advisory data in its response (tier1 field) alongside the built-in scanner’s verdict.

External Skill Directories

If you maintain skills outside of Mibyan — for example, a shared ~/.agents/skills/ directory used by multiple AI tools — you can tell Mibyan to scan those directories too. Add external_dirs under the skills section in ~/.mibyan/config.yaml:

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Paths support ~ expansion and ${VAR} environment variable substitution.

How it works

Create locally, update in place: New agent-created skills are written to ~/.mibyan/skills/ (or skills.create_dir when configured — see below). Existing skills are modified where they are found, including skills under external_dirs, when the agent uses skill_manage actions such as patch (targeted or full rewrite), write_file, remove_file, or delete.
External dirs are not a write-protection boundary: If an external skill directory is writable by the Mibyan process, agent-managed skill updates can change files in that directory. Use filesystem permissions or a separate profile/toolset setup if shared external skills must stay read-only.
Local precedence: If the same skill name exists in both the local dir and an external dir, the local version wins.
Full integration: External skills appear in the system prompt index, skills_list, skill_view, and as /skill-name slash commands — no different from local skills.
Non-existent paths are silently skipped: If a configured directory doesn’t exist, Mibyan ignores it without errors. Useful for optional shared directories that may not be present on every machine.

Example

~/.mibyan/skills/               # Local (primary, read-write)
├── devops/deploy-k8s/
│   └── SKILL.md
└── mlops/axolotl/
    └── SKILL.md

~/.agents/skills/               # External (shared, mutable if writable)
├── my-custom-workflow/
│   └── SKILL.md
└── team-conventions/
    └── SKILL.md

All four skills appear in your skill index. If you create a new skill called my-custom-workflow locally, it shadows the external version.

Redirecting Skill Creation (`skills.create_dir`)

By default the agent writes new skills to the profile-local ~/.mibyan/skills/. If you want agent-created skills to land somewhere else — a shared “brain” directory, a git-tracked repo, or a fleet-wide skills volume — set create_dir under the skills section:

skills:
  create_dir: /opt/brain/skills

What this changes:

skill_manage create writes there. New skills (including category subdirectories) are created under create_dir instead of the local skills dir. The directory is created on first write if it doesn’t exist.
The agent’s instructions follow the config. Every agent-facing instruction that names the skill-creation path — the skill_manage tool description and related prompt text — dynamically renders the configured directory, so the agent is told to create skills there. No system-prompt overrides or filesystem tricks needed.
The directory is fully integrated. Skills under create_dir are scanned alongside the local dir: they appear in the skill index, skills_list, skill_view, slash commands, and can be patched or deleted like any local skill.
Everything else stays local. Existing skills are still modified in place wherever they live; bundled skill sync, the hub, and the curator keep operating on the profile-local dir.

Paths support ~ expansion and ${VAR} substitution; relative paths resolve against your Mibyan home. Setting create_dir to the local skills dir is the same as leaving it unset.

Project-Local Skills

Repos can carry their own skills, active only for sessions started inside that project — the same pattern other agent harnesses use for repo-local configuration. When you launch Mibyan inside a git checkout, it looks for skills in:

<project-root>/.mibyan/skills/    # Mibyan-native location
<project-root>/.agents/skills/    # cross-tool convention (shared with other agent CLIs)

The project root is the nearest ancestor directory containing .git (worktrees and submodules count).

Trusting a project

Skills are procedure documents the agent follows, so Mibyan does not auto-load them from arbitrary cloned repos. The first time you run Mibyan in a repo with project skills, the banner shows a notice:

◆ 3 project skill(s) found in /home/you/myproject but not loaded — run `mibyan skills trust` to enable them.

Trust the repo once (from inside it, or by passing the path):

mibyan skills trust             # trust the current repo
mibyan skills trust ~/myproject # or explicitly
mibyan skills untrust           # revoke

Trusted roots are stored in skills.trusted_project_dirs in ~/.mibyan/config.yaml. Set skills.project_discovery: false to turn the feature off entirely (no scanning, no notices).

Precedence

Project skills are the highest-precedence tier: project → local (~/.mibyan/skills/) → external_dirs. A project skill named deploy overrides a same-named profile or bundled skill for sessions inside that repo — that’s the point: vendored repo skills win on their home turf, without touching your global profile. Project skills are tagged [project] in the agent’s skill index so provenance stays visible. Like external dirs, project skill directories are treated as repo-owned: autonomous skill maintenance (the curator) never modifies them, and new agent-created skills always go to ~/.mibyan/skills/.

Scan-time quarantine

Trust is a repo-level decision, but a repo’s skill content changes with every git pull. To close that gap, every project skill is scanned with the same security scanner used for Skills Hub installs before it enters the index. A skill whose scan verdict is dangerous (prompt-injection directives, credential-exfiltration commands, hidden-text tricks) is quarantined: it does not appear in the skill index, skills_list, slash commands, and refuses to load by name with an explanatory error. Scans are content-hash cached under ~/.mibyan/cache/project_skill_scans/ (never inside your repo) and re-run automatically when the skill’s content changes.

Non-interactive surfaces (cron, API, ACP)

Cron jobs and other non-interactive surfaces inherit your interactive trust decision — they never prompt and never auto-trust. The project root resolves from the surface’s working directory (a cron job’s workdir, via the same mechanism the terminal tool uses). A cron job whose workdir is inside a repo you previously trusted loads that repo’s project skills; a job in an untrusted or undecided repo loads none. In the TUI and Desktop the project root follows each session’s workspace (the directory shown in the sidebar / set with the workspace picker), so starting mibyan --tui inside a trusted repo registers its project skills as slash commands even when terminal.cwd is left at the default placeholder .; two sessions open in two repos each see their own.

Skill Bundles

Skill bundles are tiny YAML files that group several skills under a single slash command. When you run /<bundle-name>, every skill listed in the bundle loads at once — useful when a particular task always benefits from the same set of skills together.

Quick example

# Create a bundle for backend feature work
mibyan bundles create backend-dev \
  --skill github-code-review \
  --skill test-driven-development \
  --skill github-pr-workflow \
  -d "Backend feature work — review, test, PR workflow"

Then in the CLI or any gateway platform:

/backend-dev refactor the auth middleware

The agent receives all three skills loaded into one user message, with any text after the slash command attached as a user instruction.

YAML schema

Bundles live in ~/.mibyan/skill-bundles/<slug>.yaml and look like this:

name: backend-dev
description: Backend feature work — review, test, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Always start by writing failing tests, then implement.
  Open the PR through the standard workflow with co-author tags.

Fields:

name (optional — defaults to the filename stem) — the bundle’s display name. Normalized to a hyphen slug for the slash command (Backend Dev → /backend-dev).
description (optional) — short text shown in /bundles and mibyan bundles list.
skills (required, non-empty list) — skill names or paths relative to your skills directory. Use the same identifier you’d pass to /<skill-name>.
instruction (optional) — extra guidance prepended to the loaded skill content. Useful for codifying “how we always use these together.”

Managing bundles

# List all installed bundles
mibyan bundles list

# Inspect one bundle
mibyan bundles show backend-dev

# Create a bundle interactively (omit --skill flags to enter them one per line)
mibyan bundles create research

# Overwrite an existing bundle
mibyan bundles create backend-dev --skill ... --force

# Delete a bundle
mibyan bundles delete backend-dev

# Re-scan ~/.mibyan/skill-bundles/ and report changes
mibyan bundles reload

From inside a chat session, /bundles lists every installed bundle and its skills.

Behavior

Bundles take precedence over individual skills when slugs collide. If you name a bundle research and you also have a skill called research, /research invokes the bundle. This is intentional — you opted into the bundle by naming it.
Missing skills are skipped, not fatal. If a bundle lists skill-foo and you haven’t installed it, the bundle still loads the skills that do resolve, and the agent gets a note listing what was skipped.
Bundles work in every surface — interactive CLI, TUI, dashboard chat, and every gateway platform (Telegram, Discord, Slack, …) — because dispatch is centralized in the same place as individual skill commands.
Bundles do not invalidate the prompt cache. They generate a fresh user message at invocation time, the same way /<skill-name> does — no system prompt mutation.

When bundles beat installing each skill manually

Use a bundle when:

You always pair the same skills for a recurring task (/backend-dev, /release-prep, /incident-response).
You want a one-character-shorter mental model than typing several /skill invocations in a row.
You want to ship a team-wide “task profile” by checking the bundle YAML into a shared dotfiles repo and symlinking it into ~/.mibyan/skill-bundles/.

A bundle is just a YAML alias — it doesn’t install skills for you. The skills themselves must already be present (in ~/.mibyan/skills/ or an external skill directory). Otherwise the bundle invocation just skips the missing ones.

Agent-Managed Skills (skill_manage tool)

The agent can create, update, and delete its own skills via the skill_manage tool. This is the agent’s procedural memory — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse. Skills and memory work together in the self-improvement loop: memory stores small durable facts that should always be in context, while skills store longer procedures that should load only when relevant. The background review can suggest or stage skill changes after a session, but the write-approval gate below lets you require human review before those changes land.

When the Agent Creates Skills

The system prompt asks the agent to record a non-trivial workflow with skill_manage for future reuse. In practice that covers:

When it worked out a multi-step workflow worth repeating
When it hit errors or dead ends and found the working path
When the user corrected its approach

What a skill entry looks like

A skill is the instructions for doing a class of task the most efficient and correct way, to your specifications: the procedure in order, the commands and tool calls that work, how you want the result to look, and the pitfalls that cost time. Whether written in a foreground turn, by the background review, or by the curator’s consolidation pass, it captures lessons, not logs: a pitfall is a generalizable rule plus one clause of why (the mechanism), attached to the step it affects, stated once. Incident narration, PR or issue numbers, dates, and quoted chat are not skill content; the rule has to stand without the story behind it. Always-on rules live in SKILL.md itself; references/ holds a small set of files named by topic (a decision table, a recipe, provider quirks), extended in place rather than accumulated one file per session. Skills also do not restate what is already loaded every turn (the repo’s AGENTS.md, tool schemas). skill_manage runs an advisory linter on create, on SKILL.md patches, and on references/ writes and returns its findings in the tool result. Three rules exist specifically for this shape: incident-log-shape (a body dense in PR/issue numbers), references-sprawl (more than 60 reference files), and oversized-body (a SKILL.md body past ~24k chars — skill_view loads the whole file and it stays in context for the rest of the session). They warn; they never block a write.

Actions

Action	Use for	Key params
`create`	New skill from scratch	`name`, `content` (full SKILL.md), optional `category`
`patch`	Targeted fixes (preferred)	`name`, `old_string`, `new_string`
`patch` with `content`	Major structural rewrites (replaces the whole SKILL.md; `edit` is the legacy alias)	`name`, `content`
`delete`	Remove a skill entirely	`name`
`write_file`	Add/update supporting files	`name`, `file_path`, `file_content`
`remove_file`	Remove a supporting file	`name`, `file_path`

Each action is advertised as its own shape: the text slot belongs to one action only (content → create / full rewrite, new_string → targeted patch, file_content → write_file). An op that carries another action’s slot — e.g. file_content on a create — is invalid against the tool schema (grammar-constrained local backends never emit it) and, if it arrives anyway, is rejected before any op in the batch is applied, with an error naming the key the text sits in and where to move it.

The targeted patch is preferred for updates — it’s more token-efficient than a full rewrite because only the changed text appears in the tool call.

Gating agent skill writes (`skills.write_approval`)

By default the agent writes skills freely — including from the background self-improvement review that runs after a turn. If you’d rather approve every skill write first (small models that misjudge what they learned, secure environments, or just wanting eyes on the self-improvement loop), turn on the write-approval gate:

skills:
  write_approval: false     # false = write freely (default) | true = require approval

When write_approval: true, every skill_manage write (create / edit / patch / delete / write_file / remove_file) is staged instead of committed — a SKILL.md is too large to review inline, so staging applies regardless of whether the write came from a foreground turn or the background review. Staged writes survive restarts under ~/.mibyan/pending/skills/ and are reviewed with the same familiar approve/deny flow as dangerous commands:

/skills pending             # list staged skill writes + a one-line gist each
/skills diff <id>           # full unified diff (best viewed in CLI or dashboard)
/skills approve <id>        # apply it (or 'all')
/skills reject <id>         # drop it (or 'all')
/skills approval on         # turn the gate on (or 'off') and persist it

The review surface works in the interactive CLI and on messaging platforms (diff output is truncated for chat bubbles — read the full diff on the CLI or in the pending JSON file). Memory writes have the same gate under memory.write_approval — see Controlling memory writes.

The separate skills.guard_agent_created setting is a content scanner (dangerous-pattern heuristics), not an approval gate — the two are independent. See Guard on agent-created skill writes.

Skills Hub

Browse, search, install, and manage skills from online registries, skills.sh, direct well-known skill endpoints, and official optional skills. Unfiltered searches (CLI, TUI, and the dashboard) are answered from a cached centralized index that covers the external registries. That index is rebuilt periodically, so when it has no match for your query Mibyan also asks skills.sh, ClawHub, LobeHub and well-known endpoints directly — a skill published minutes ago still shows up. That extra pass gets at most 8 seconds of the search budget, so a slow registry cannot turn a miss into a long wait. Custom GitHub taps are not part of that fallback (search them with --source github, or via the index once it catches up), and provider filters such as --source nvidia do not trigger it (those registries carry no provider data).

Common commands

mibyan skills browse                              # Browse all hub skills (official first)
mibyan skills browse --source official            # Browse only official optional skills
mibyan skills search kubernetes                   # Search all sources
mibyan skills search react --source skills-sh     # Search the skills.sh directory
mibyan skills search https://mintlify.com/docs --source well-known
mibyan skills inspect openai/skills/k8s           # Preview before installing
mibyan skills install openai/skills/k8s           # Install with security scan
mibyan skills install official/security/1password
mibyan skills install skills-sh/vercel-labs/json-render/json-render-react --force
mibyan skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify
mibyan skills install https://sharethis.chat/SKILL.md              # Direct URL (+ referenced support files)
mibyan skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none
mibyan skills list --source hub                   # List hub-installed skills
mibyan skills check                               # Check installed hub skills for upstream updates
mibyan skills update                              # Reinstall hub skills with upstream changes when needed
mibyan skills audit                               # Re-scan all hub skills for security
mibyan skills uninstall k8s                       # Remove a hub skill
mibyan skills reset google-workspace              # Un-stick a bundled skill from "user-modified" (see below)
mibyan skills reset google-workspace --restore    # Also restore the bundled version, deleting your local edits
mibyan skills publish skills/my-skill --to github --repo owner/repo
mibyan skills snapshot export setup.json          # Export skill config
mibyan skills tap add myorg/skills-repo           # Add a custom GitHub source

Supported hub sources

Source	Example	Notes
`official`	`official/security/1password`	Optional skills shipped with Mibyan.
`skills-sh`	`skills-sh/vercel-labs/agent-skills/vercel-react-best-practices`	Searchable via `mibyan skills search <query> --source skills-sh`. Mibyan resolves alias-style skills when the skills.sh slug differs from the repo folder.
`well-known`	`well-known:https://mintlify.com/docs/.well-known/skills/mintlify`	Skills served directly from `/.well-known/skills/index.json` on a website. Search using the site or docs URL.
`url`	`https://sharethis.chat/SKILL.md`	Direct HTTP(S) URL to `SKILL.md` plus explicitly referenced support files. Name resolution: frontmatter → URL slug → interactive prompt → `--name` flag.
`github`	`openai/skills/k8s`	Direct GitHub repo/path installs and custom taps.
`clawhub`, `lobehub`, `browse-sh`	Source-specific identifiers	Community or marketplace integrations.

Integrated hubs and registries

Mibyan currently integrates with these skills ecosystems and discovery sources:

1. Official optional skills (`official`)

These are maintained in the Mibyan repository itself and install with built-in trust.

Catalog: Official Optional Skills Catalog
Source in repo: optional-skills/
Example:

mibyan skills browse --source official
mibyan skills install official/security/1password

2. skills.sh (`skills-sh`)

This is Vercel’s public skills directory. Mibyan can search it directly, inspect skill detail pages, resolve alias-style slugs, and install from the underlying source repo.

Directory: skills.sh
CLI/tooling repo: vercel-labs/skills
Official Vercel skills repo: vercel-labs/agent-skills
Example:

mibyan skills search react --source skills-sh
mibyan skills inspect skills-sh/vercel-labs/json-render/json-render-react
mibyan skills install skills-sh/vercel-labs/json-render/json-render-react --force

3. Well-known skill endpoints (`well-known`)

This is URL-based discovery from sites that publish /.well-known/skills/index.json. It is not a single centralized hub — it is a web discovery convention.

Example live endpoint: Mintlify docs skills index
Reference server implementation: vercel-labs/skills-handler
Example:

mibyan skills search https://mintlify.com/docs --source well-known
mibyan skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify
mibyan skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

4. Direct GitHub skills (`github`)

Mibyan can install directly from GitHub repositories and GitHub-based taps. This is useful when you already know the repo/path or want to add your own custom source repo. Default taps (browsable without any setup):

openai/skills
anthropics/skills
huggingface/skills
NVIDIA/skills — NVIDIA-verified skills (signed skill.oms.sig + governance skill-card.md)
garrytan/gstack
K-Dense-AI/scientific-agent-skills and synthetic-sciences/openscience — ~480 scientific research skills (bioinformatics, chemistry, physics, ML training, scholarly tooling), grouped under one science category. Community trust: every install is security-scanned. Many wrap third-party tools with their own licenses (some GPL; KEGG requires a commercial license for non-academic use) — check each skill’s prerequisites.
Example:

mibyan skills install openai/skills/k8s
mibyan skills tap add myorg/skills-repo

Category groupings (skills.sh.json). A GitHub tap may ship a skills.sh.json file at its repo root following the skills.sh schema. Its groupings (each with a title and a list of skill names) are read at index time and become the category labels shown in the Skills Hub page — instead of a tag-derived guess. This is generic: any tap that ships the file gets real categorization, no Mibyan-side changes required.

{
  "$schema": "https://skills.sh/schemas/skills.sh.schema.json",
  "groupings": [
    { "title": "Inference AI", "skills": ["dynamo-recipe-runner", "dynamo-router-sla"] },
    { "title": "Decision Optimization", "skills": ["cuopt-developer", "cuopt-install"] }
  ]
}

5. ClawHub (`clawhub`)

A third-party skills marketplace integrated as a community source.

Site: clawhub.ai
Mibyan source id: clawhub

6. LobeHub (`lobehub`)

Mibyan can search and convert agent entries from LobeHub’s public catalog into installable Mibyan skills.

Site: LobeHub
Public agents index: chat-agents.lobehub.com
Backing repo: lobehub/lobe-chat-agents
Mibyan source id: lobehub

7. browse.sh (`browse-sh`)

Mibyan integrates with browse.sh, Browserbase’s catalog of 200+ site-specific browser-automation SKILL.md files (Airbnb, Amazon, arXiv, 12306.cn, Etsy, Xero, and many more). Each skill describes how to drive one website end-to-end and is suitable for use with Mibyan’ browser tools and any browser-automation skills you already have installed.

Site: browse.sh
Catalog API: https://browse.sh/api/skills
Mibyan source id: browse-sh
Trust level: community

mibyan skills search airbnb --source browse-sh
mibyan skills inspect browse-sh/airbnb.com/search-listings-ddgioa
mibyan skills install browse-sh/airbnb.com/search-listings-ddgioa

Identifiers use the form browse-sh/<hostname>/<task-id> and match the slug exposed by the browse.sh catalog. Content is resolved through the per-skill detail endpoint (/api/skills/<slug> → skillMdUrl), not through the catalog’s GitHub sourceUrl.

8. Direct URL (`url`)

Install SKILL.md directly from any HTTP(S) URL — useful when an author hosts a skill on their own site (no hub listing, no GitHub path to type). Mibyan also fetches explicitly referenced files under references/, templates/, scripts/, assets/, and examples/, then scans and installs the complete bundle.

Mibyan source id: url
Identifier: the URL itself (no prefix needed)
Scope: SKILL.md plus exact referenced support files in the allowlisted directories. Mibyan does not enumerate or copy unrelated files from the host.

mibyan skills install https://sharethis.chat/SKILL.md
mibyan skills install https://example.com/my-skill/SKILL.md --category productivity

Name resolution, in order:

name: field in the SKILL.md YAML frontmatter (recommended — every well-formed skill has one).
Parent directory name from the URL path (e.g. .../my-skill/SKILL.md → my-skill, or .../my-skill.md → my-skill), when it’s a valid identifier (^[a-z][a-z0-9_-]*$).
Interactive prompt on a terminal with a TTY.
On non-interactive surfaces (the /skills install slash command inside the TUI, gateway platforms, scripts), a clean error pointing at the --name override.

# Frontmatter has no name and the URL slug is unhelpful — supply one:
mibyan skills install https://example.com/SKILL.md --name sharethis-chat

# Or inside a chat session:
/skills install https://example.com/SKILL.md --name sharethis-chat

Trust level is always community — the same security scan runs as for every other source. The URL is stored as the install identifier, so mibyan skills update re-fetches from the same URL automatically when you want to refresh.

Security scanning and `--force`

All hub-installed skills go through a security scanner that checks for data exfiltration, prompt injection, destructive commands, supply-chain signals, and other threats. mibyan skills inspect ... now also surfaces upstream metadata when available:

repo URL
skills.sh detail page URL
install command
weekly installs
upstream security audit statuses
well-known index/endpoint URLs

Use --force when you have reviewed a third-party skill and want to override a non-dangerous policy block:

mibyan skills install skills-sh/anthropics/skills/pdf --force

Important behavior:

--force can override policy blocks for caution/warn-style findings.
--force does not override a dangerous scan verdict.
Official optional skills (official/...) are treated as built-in trust and do not show the third-party warning panel.

Trust levels

Level	Source	Policy
`builtin`	Ships with Mibyan	Always trusted
`official`	`optional-skills/` in the repo	Built-in trust, no third-party warning
`trusted`	Trusted registries/repos such as `openai/skills`, `anthropics/skills`, `huggingface/skills`, `NVIDIA/skills`	More permissive policy than community sources
`community`	Everything else (`skills.sh`, well-known endpoints, custom GitHub repos, most marketplaces)	Non-dangerous findings can be overridden with `--force`; `dangerous` verdicts stay blocked

Update lifecycle

The hub now tracks enough provenance to re-check upstream copies of installed skills:

mibyan skills check          # Report which installed hub skills changed upstream
mibyan skills update         # Reinstall only the skills with updates available
mibyan skills update react   # Update one specific installed hub skill
mibyan skills update react --force   # Overwrite a skill you've edited locally

This uses the stored source identifier plus the current upstream bundle content hash to detect drift. Checks skip network requests for missing or non-directory installs (orphaned) and unsafe or unresolvable recorded paths (invalid_install). Missing-directory entries can be removed with mibyan skills uninstall <name>; invalid paths require inspecting and repairing the active profile’s skills/.hub/lock.json before retrying. No entries are removed automatically. Valid installs continue to use their source adapter’s existing synchronous fetch and transport timeouts. There is no strict total deadline for an update check: an unreachable or slow source for an existing install can still delay later entries. Skills you have edited locally (the on-disk content no longer matches the hash recorded at install time) are skipped by mibyan skills update so your changes are never silently overwritten. Pass --force to replace them with the upstream version anyway.

GitHub rate limitsSkills hub operations use the GitHub API, which has a rate limit of 60 requests/hour for unauthenticated users. If you see rate-limit errors during install or search, set GITHUB_TOKEN in your .env file to increase the limit to 5,000 requests/hour. The error message includes an actionable hint when this happens.

Publishing a custom skill tap

If you want to share a curated set of skills — for your team, your org, or publicly — you can publish them as a tap: a GitHub repository other Mibyan users add with mibyan skills tap add <owner/repo>. No server, no registry sign-up, no release pipeline. Just a directory of SKILL.md files.

Repo layout

A tap is any GitHub repo (public or private — private needs GITHUB_TOKEN) laid out like this:

owner/repo
├── skills/                       # default path; configurable per-tap
│   ├── my-workflow/
│   │   ├── SKILL.md              # required
│   │   ├── references/           # optional supporting files
│   │   ├── templates/
│   │   └── scripts/
│   ├── another-skill/
│   │   └── SKILL.md
│   └── third-skill/
│       └── SKILL.md
└── README.md                     # optional but helpful

Rules:

Each skill lives in its own directory under the tap’s root path (default skills/).
The directory name becomes the skill’s install slug.
Each skill directory must contain a SKILL.md with standard SKILL.md frontmatter (name, description, plus optional metadata.mibyan.tags, version, author, platforms, metadata.mibyan.config).
Subdirectories like references/, templates/, scripts/, assets/ are downloaded alongside SKILL.md at install time.
Skills whose directory name starts with . or _ are ignored.

Mibyan discovers skills by listing every subdirectory of the tap path and probing each for SKILL.md.

Minimal tap example

my-org/mibyan-skills
└── skills/
    └── deploy-runbook/
        └── SKILL.md

skills/deploy-runbook/SKILL.md:

---
name: deploy-runbook
description: Our deployment runbook — services, rollback, Slack channels
version: 1.0.0
author: My Org Platform Team
metadata:
  mibyan:
    tags: [deployment, runbook, internal]
---

# Deploy Runbook

Step 1: ...

After pushing that to GitHub, any Mibyan user can subscribe and install:

mibyan skills tap add my-org/mibyan-skills
mibyan skills search deploy
mibyan skills install my-org/mibyan-skills/deploy-runbook

Non-default paths

If your skills don’t live under skills/ (common when you’re adding a skills/ subtree to an existing project), edit the tap entry in ~/.mibyan/skills/.hub/taps.json:

{
  "taps": [
    {"repo": "my-org/platform-docs", "path": "internal/skills/"}
  ]
}

The mibyan skills tap add CLI defaults new taps to path: "skills/"; edit the file directly if you need a different path. mibyan skills tap list shows the effective path per tap.

Installing individual skills directly (without adding a tap)

Users can also install a single skill from any public GitHub repo without adding the whole repo as a tap:

mibyan skills install owner/repo/skills/my-workflow

Useful when you want to share one skill without asking the user to subscribe to your whole registry.

Trust levels for taps

New taps are assigned community trust by default. Skills installed from them run through the standard security scan and show the third-party warning panel on first install. If your org or a widely-trusted source should get higher trust, add its repo to TRUSTED_REPOS in tools/skills_guard.py (requires a Mibyan core PR).

Tap management

mibyan skills tap list                                # show all configured taps
mibyan skills tap add myorg/skills-repo               # add (default path: skills/)
mibyan skills tap remove myorg/skills-repo            # remove

Inside a running session:

/skills tap list
/skills tap add myorg/skills-repo
/skills tap remove myorg/skills-repo

Taps are stored in ~/.mibyan/skills/.hub/taps.json (created on demand).

Bundled skill updates (`mibyan skills reset`)

Mibyan ships with a set of bundled skills in skills/ inside the repo. On install and on every mibyan update, a sync pass copies those into ~/.mibyan/skills/ and records a manifest at ~/.mibyan/skills/.bundled_manifest mapping each skill name to the content hash at the time it was synced (the origin hash). On each sync, Mibyan recomputes the hash of your local copy and compares it to the origin hash:

Unchanged → safe to pull upstream changes, copy the new bundled version in, record the new origin hash.
Changed → treated as user-modified and skipped forever, so your edits never get stomped.

Generated runtime caches inside a skill (__pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, and a .pyc sitting next to its .py) are not part of the hash, so running a skill’s helper script never marks it user-modified or hides it from mibyan skills list-modified / diff. The protection is good, but it has one sharp edge. If you edit a bundled skill and then later want to abandon your changes and go back to the bundled version by just copy-pasting from ~/.mibyan/mibyan-agent/skills/, the manifest still holds the old origin hash from whenever the last successful sync ran. Your fresh copy-paste contents (current bundled hash) won’t match that stale origin hash, so sync keeps flagging it as user-modified. mibyan skills reset is the escape hatch:

# Safe: clears the manifest entry for this skill. Your current copy is preserved,
# but the next sync re-baselines against it so future updates work normally.
mibyan skills reset google-workspace

# Full restore: also deletes your local copy and re-copies the current bundled
# version. Use this when you want the pristine upstream skill back.
mibyan skills reset google-workspace --restore

# Non-interactive (e.g. in scripts or TUI mode) — skip the --restore confirmation.
mibyan skills reset google-workspace --restore --yes

The same command works in chat as a slash command:

/skills reset google-workspace
/skills reset google-workspace --restore

ProfilesEach profile has its own .bundled_manifest under its own mibyan_HOME, so mibyan -p coder skills reset <name> only affects that profile.

Slash commands (inside chat)

All the same commands work with /skills:

/skills browse
/skills search react --source skills-sh
/skills search https://mintlify.com/docs --source well-known
/skills inspect skills-sh/vercel-labs/json-render/json-render-react
/skills install openai/skills/skill-creator --force
/skills check
/skills update
/skills reset google-workspace
/skills list

Official optional skills still use identifiers like official/security/1password and official/migration/openclaw-migration.

​Browse and install in Desktop

​Install from the website

​Starting with a blank slate

​Using Skills

​Stacking multiple skills in one command

​Learning a skill from sources (/learn)

​Large sources become knowledge-base skills

​Progressive Disclosure

​SKILL.md Format

​Platform-Specific Skills

​Skill output and media delivery

​Forcing document-style delivery: [[as_document]]

​Conditional Activation (Fallback Skills)

​Secure Setup on Load

​Skill Config Settings

​Skill Directory Structure

​Advisory SkillEvaluator scan

​External Skill Directories

​How it works

​Example

​Redirecting Skill Creation (skills.create_dir)

​Project-Local Skills

​Trusting a project

​Precedence

​Scan-time quarantine

​Non-interactive surfaces (cron, API, ACP)

​Skill Bundles

​Quick example

​YAML schema

​Managing bundles

​Behavior

​When bundles beat installing each skill manually

​Agent-Managed Skills (skill_manage tool)

​When the Agent Creates Skills

​What a skill entry looks like

​Actions

​Gating agent skill writes (skills.write_approval)

​Skills Hub

​Common commands

​Supported hub sources

​Integrated hubs and registries

​1. Official optional skills (official)

​2. skills.sh (skills-sh)

​3. Well-known skill endpoints (well-known)

​4. Direct GitHub skills (github)

​5. ClawHub (clawhub)

​6. LobeHub (lobehub)

​7. browse.sh (browse-sh)

​8. Direct URL (url)

​Security scanning and --force

​Trust levels

​Update lifecycle

​Publishing a custom skill tap

​Repo layout

​Minimal tap example

​Non-default paths

​Installing individual skills directly (without adding a tap)

​Trust levels for taps

​Tap management

​Bundled skill updates (mibyan skills reset)

​Slash commands (inside chat)

Browse and install in Desktop

Install from the website

Starting with a blank slate

Using Skills

Stacking multiple skills in one command

Learning a skill from sources (`/learn`)

Large sources become knowledge-base skills

Progressive Disclosure

SKILL.md Format

Platform-Specific Skills

Skill output and media delivery

Forcing document-style delivery: `[[as_document]]`

Conditional Activation (Fallback Skills)

Secure Setup on Load

Skill Config Settings

Skill Directory Structure

Advisory SkillEvaluator scan

External Skill Directories

How it works

Example

Redirecting Skill Creation (`skills.create_dir`)

Project-Local Skills

Trusting a project

Precedence

Scan-time quarantine

Non-interactive surfaces (cron, API, ACP)

Skill Bundles

Quick example

YAML schema

Managing bundles

Behavior

When bundles beat installing each skill manually

Agent-Managed Skills (skill_manage tool)

When the Agent Creates Skills

What a skill entry looks like

Actions

Gating agent skill writes (`skills.write_approval`)

Skills Hub

Common commands

Supported hub sources

Integrated hubs and registries

1. Official optional skills (`official`)

2. skills.sh (`skills-sh`)

3. Well-known skill endpoints (`well-known`)

4. Direct GitHub skills (`github`)

5. ClawHub (`clawhub`)

6. LobeHub (`lobehub`)

7. browse.sh (`browse-sh`)

8. Direct URL (`url`)

Security scanning and `--force`

Trust levels

Update lifecycle

Publishing a custom skill tap

Repo layout

Minimal tap example

Non-default paths

Installing individual skills directly (without adding a tap)

Trust levels for taps

Tap management

Bundled skill updates (`mibyan skills reset`)

Slash commands (inside chat)