Skills

Level	Purpose	Host path	Runtime path inside sandbox
Workspace-level (global skills)	Shared tools available to all conversations in a workspace	<workspace>/skills/<skill-name>/	/workspace/skills/<skill-name>/
Conversation-level (local skills)	Tools for one conversation / channel / DM only	<workspace>/<office-key>/skills/<skill-name>/	/workspace/<office-key>/skills/<skill-name>/
Package skills	Skills shipped by an installed package	a git checkout under the state dir	/mikan/packages/<slug>/skills/ (read-only)

The office key is the v1-<platform>-<readable-id>-<hash> directory name mikan derives for each conversation; you do not construct it by hand. The admin portal’s skills view lists both levels and can create a skill in either.

Note

mikan loads workspace-level skills first, then conversation-level skills. If both sides define the same name, the conversation-level skill overrides the workspace-level skill.

Workspace-level skills need a trusted door

Under the default isolated door policy a conversation sees only its own office, so workspace-level skills are neither mounted nor offered to the agent — the prompt tells it to keep skills in its own office instead. Workspace-level skills require a trusted shared-support or full layout. See Sandbox.

Directory structure

<workspace>/
├── skills/
│   └── my-global-tool/
│       ├── SKILL.md
│       └── run.sh
└── v1-slack-c0123456789-<digest>/
    └── skills/
        └── my-local-tool/
            ├── SKILL.md
            └── run.sh

A directory containing SKILL.md is treated as one skill root and is not searched recursively. mikan also discovers standalone .md files directly under a configured skills directory.

A directory-based skill uses SKILL.md:

---
name: my-tool
description: Does something useful
---

Usage: {baseDir}/run.sh <args>

name and description are required. Use paths relative to the skill directory, or write the runtime-visible absolute path shown in the table above. {baseDir} is not expanded automatically.

Which level to use

Workspace-level skills are good for shared tools: company APIs, common scripts, release helpers, reporting tools, or any capability used by multiple conversations. They require a trusted door policy.

Conversation-level skills are good for local tools: a specific channel workflow, a temporary helper, or tools that should not appear in other conversations. They work under every door policy, and are the only writable level an isolated office has.

Package skills are for distributing a skill set across installations. They mount read-only, outside /workspace, because the host owns those files — the directory is a git checkout that an update replaces wholesale, so an agent edit would be discarded on the next refresh. The filesystem refuses the write instead.