---
name: skill-building
description: Design and create agent skill packages — instruction-based and MCP-based skills, manifest format
---

# Skill Building

This skill teaches you how to create Markus skill packages — directory-based artifacts that teach agents new capabilities. A skill can work in two ways (or both):

1. **Instruction-based**: A `SKILL.md` file with instructions injected into the agent's context, guiding it to use existing tools in new ways.
2. **MCP-based**: A bundled MCP server (script) that provides entirely new tools to the agent. The skill directory can contain any scripts, config files, or resources the MCP server needs.

Most skills are instruction-based. Use MCP-based skills when the capability requires new tools that don't exist yet (e.g., connecting to an external API, browser automation, hardware control).

## Artifact Directory

**CRITICAL**: Skill artifacts MUST be saved under this exact path — the Builder page, install system, and deliverable detection all depend on it:

```
~/.markus/builder-artifacts/skills/{skill-name}/
├── skill.json       # Manifest (auto-created from your JSON output)
├── SKILL.md         # Instruction document (you write via file_write)
├── README.md        # Human-readable documentation (optional)
└── ...              # Any other files: scripts, MCP servers, configs, templates, etc.
```

**Do NOT write artifacts to `~/.markus/shared/`, your working directory, or any other location.** Only `~/.markus/builder-artifacts/skills/` is recognized by the system.

A skill directory can contain **any files** needed for the skill to work — not just SKILL.md and README.md. For example:
- **MCP server scripts** (e.g., `server.mjs`) that provide new tools to the agent
- **Configuration templates** or data files
- **Helper scripts** used by the instructions

When the user **installs** the artifact, the **entire directory** (all files) is deployed to `~/.markus/skills/{skill-name}/`. `SKILL.md` is loaded and injected into the agent's context when the skill is activated. If the manifest declares `mcpServers`, those servers are started and their tools registered to the agent. `skill.json` contains metadata used by the skill registry. `README.md` provides documentation for humans browsing or sharing the skill.

## Two-Step Workflow

Output the skill in two steps — manifest first, then content files. **Never put file content inline in the JSON.**

### Chat Mode vs Task Mode

- **Chat mode** (user conversation): Output the manifest JSON in a ```json code block → system auto-saves and creates the directory → then use `file_write` for each content file.
- **Task mode** (assigned task): Use `file_write` to write the manifest JSON file directly (e.g., `file_write("~/.markus/builder-artifacts/skills/{name}/skill.json", ...)`) → then use `file_write` for each content file. When submitting deliverables, set the reference to the artifact directory path.
- **A2A mode** (agent-to-agent): Same as task mode — write all files via `file_write`.

### Step 1: Output Manifest JSON

**In chat mode**: Output the skill configuration as a JSON code block. The system auto-saves it.
**In task/A2A mode**: Write the manifest JSON file directly via `file_write`.

This JSON contains ONLY metadata — **no file content**.

**Instruction-based skill** (most common):
```json
{
  "type": "skill",
  "name": "skill-name-kebab-case",
  "displayName": "Skill Name",
  "version": "1.0.0",
  "description": "When and why an agent should use this skill",
  "author": "Your Name",
  "category": "custom",
  "tags": ["tag1", "tag2"],
  "skill": {
    "skillFile": "SKILL.md"
  }
}
```

**MCP-based skill** (provides new tools via a bundled server script):
```json
{
  "type": "skill",
  "name": "my-api-connector",
  "displayName": "My API Connector",
  "version": "1.0.0",
  "description": "Connect to My API for data retrieval and actions",
  "author": "Your Name",
  "category": "custom",
  "tags": ["api", "connector"],
  "skill": {
    "skillFile": "SKILL.md",
    "requiredPermissions": ["network"],
    "mcpServers": {
      "my-api": {
        "command": "node",
        "args": ["${SKILL_DIR}/server.mjs"]
      }
    }
  }
}
```

**Notes on MCP servers:**
- `${SKILL_DIR}` is resolved at load time to the skill's actual directory path — use it to reference bundled scripts.
- The `command` can be any executable (`node`, `python3`, `npx`, etc.).
- The MCP server communicates via JSON-RPC 2.0 over stdio (stdin/stdout).
- Tool names exposed by MCP servers are automatically prefixed with the server name (e.g., `my-api__tool_name`). Mention these prefixed names in SKILL.md.
- You can also use externally published MCP servers: `"command": "npx", "args": ["-y", "some-mcp-server@latest"]`.

The system automatically saves this JSON and creates the directory. After that, you proceed to write files.

### Step 2: Write Files with file_write

After the JSON is saved, write each file individually using `file_write`. The base path is `~/.markus/builder-artifacts/skills/{skill-name}/` (use the `name` from your JSON).

**Write files in this order:**

1. **SKILL.md** (REQUIRED) — The instruction document with YAML frontmatter and comprehensive Markdown body:
   - YAML frontmatter with `name` and `description` (must match manifest)
   - Overview of what the skill does
   - Step-by-step instructions referencing actual tools (or MCP tool names if MCP-based)
   - Error handling guidance
   - Examples of typical input/output

2. **MCP server script** (if MCP-based) — e.g., `server.mjs` implementing the MCP protocol over stdio. Must handle `initialize`, `tools/list`, and `tools/call` JSON-RPC methods.

3. **README.md** (optional) — Human-readable documentation for browsing or sharing.

4. **Any other files** — Helper scripts, templates, config files, data files, etc.

**Example file_write calls:**

```
file_write("~/.markus/builder-artifacts/skills/git-changelog/SKILL.md", "---\nname: git-changelog\ndescription: Generate changelogs from git history\n---\n\n# Git Changelog\n\n## Overview\n...\n\n## Instructions\n...\n\n## Examples\n...")
file_write("~/.markus/builder-artifacts/skills/git-changelog/README.md", "# Git Changelog\n\nA skill that helps agents generate changelogs from git history...\n")
```

## Field Reference

### Top-level fields
- **`type`**: Always `"skill"`
- **`name`**: **MUST be English kebab-case** (e.g., `git-changelog`, `web-scraper`). Must match `SKILL.md` frontmatter name. This is the directory name and identifier.
- **`displayName`**: Human-readable skill name, can be in any language
- **`version`**: Semver (default `"1.0.0"`)
- **`description`**: When and why an agent should use this skill (can be in any language)
- **`category`**: Typically `"custom"` for user-created skills
- **`tags`**: Array of descriptive tags

### `skill` section (REQUIRED)
- **`skillFile`**: Always `"SKILL.md"` — the entry point instruction document
- **`requiredPermissions`**: (optional) Array of permissions: `"shell"`, `"file"`, `"network"`, `"browser"`
- **`mcpServers`**: (optional) Map of MCP server name → config. Each config has `command`, `args?`, `env?`. Use `${SKILL_DIR}` in args/env to reference the skill directory.
- **`alwaysOn`**: (optional, boolean) If `true`, the skill's instructions are automatically injected into **every** agent's context at startup. Only use this for foundational skills that all agents must always follow (e.g., `self-evolution`). Default is `false` — non-alwaysOn built-in skills are listed as "available" in the agent's identity section and can be activated on-demand via `discover_tools`.

## After Creation

> **CRITICAL**: Creating an artifact is NOT the same as installing/deploying it. Creating writes files to `builder-artifacts/`; installing makes the skill available to agents in the live org. **NEVER auto-install.** Only install when the user explicitly asks. This applies to ALL modes (chat, task, A2A).

Once all files are written, tell the user:

1. **The skill has been created and saved** — summarize what was created (name, purpose, what agents can do with it).
2. **Ready to install** — the user can install from the Builder page, or ask you to install it (you would use `package_install`). Do NOT install unless asked.
3. **To modify or improve** this skill (e.g., add more instructions, update examples, fix edge cases), just continue the conversation here — describe what you want to change and I'll update the files directly.

## Guidelines

- Instructions in SKILL.md should reference actual tools: `shell_execute`, `file_read`, `file_write`, `file_edit`, `grep_search`, `glob_find`, `list_directory`, `web_fetch`, `web_search`, `gui` — or MCP tool names if the skill provides its own tools
- For MCP-based skills, document every tool with its prefixed name (e.g., `my-api__search`) in SKILL.md so the agent knows how to use them
- Be specific — include actual CLI commands, file paths, and URL patterns
- Include error handling: what to do when commands fail, pages don't load, etc.
- Provide examples of typical input/output for each workflow step
- Skills should be self-contained: an agent reading the instructions should know exactly what to do
- Consider composability: skills that work well alongside other skills
- After outputting the JSON, immediately proceed to write files via `file_write` — announce what you're writing
- When creating MCP server scripts, use only Node.js built-in modules (no npm dependencies) for maximum portability, or use `npx` to reference published packages

## Rules

- **DO NOT** use names that conflict with built-in skills. Check the dynamic context for existing skill names.
- **DO NOT** put file content in the JSON. Always use `file_write` for files.
- **DO NOT** write artifacts to `~/.markus/shared/` or your working directory. Always use `~/.markus/builder-artifacts/skills/{name}/`.
- **The `name` field MUST be English kebab-case** (e.g., `git-changelog`, not `网页抓取器`). This is the directory name and package identifier.
- The `name` field and `SKILL.md` frontmatter `name` must match exactly.
- **All top-level fields must be the correct type**: `author` must be a plain string (your name, e.g. `"John"`) — NOT an object. `tags` must be an array of strings. `version` must be semver string. `description` must be a string. The system validates the manifest on write and will reject malformed files.
