skill-building

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)
├── images/          # Skill icon images (optional)
│   └── icon.png     # Skill icon — used in UI after install
└── ...              # 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.

All modes (chat / task / A2A) — same rule

There is no chat auto-save. A JSON code block in your reply does not create files.

1. file_write("~/.markus/builder-artifacts/skills/{name}/skill.json", ...) for the manifest
2. file_write for each content file (SKILL.md, README, …)
3. In task mode, set deliverable references to the artifact directory path

You may preview JSON in chat in addition to writing files — never instead of file_write.

Step 1: Write Manifest JSON via file_write

This JSON contains ONLY metadata — no file content.

Instruction-based skill (most common):

{
  "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",
  "icon": "images/icon.png",
  "category": "custom",
  "tags": ["tag1", "tag2"],
  "skill": {
    "skillFile": "SKILL.md"
  }
}

MCP-based skill (provides new tools via a bundled server script):

{
  "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",
  "icon": "images/icon.png",
  "category": "custom",
  "tags": ["api", "connector"],
  "skill": {
    "skillFile": "SKILL.md",
    "requiredPermissions": ["network"],
    "mcpServers": {
       
         
         
      
    
  

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"].

After skill.json is written, proceed to write the remaining files with file_write.

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.

5. images/icon.png (optional) — Skill icon for UI display (see Image Assets).

Image Assets

Skill icons are abstract representations of the skill's capability — like an app icon or tool symbol. They should be clean, recognizable, and work well at small sizes.

Image	Location	Style	Purpose
Skill icon	images/icon.png	Abstract icon / symbol	Skill card in UI, published to Hub as icon

Do NOT use portraits for skill icons. Skills are tools, not team members. Portraits belong on agents.

Image Generation

Prompt style guide for generate_image:

Good prompt (do this):
  "Clean icon design for a git changelog tool, stylized git branch merging into a document,
   flat vector style, teal and white palette, square format, modern minimal"
  "Minimalist icon for a GitHub automation skill, octagon cat silhouette combined with
   gear, flat design, purple gradients, square format"
  "Abstract icon representing web scraping capability, spider-web pattern with a magnifying
   glass, geometric style, blue and orange accents, square format"

Bad prompt (don't do this):
  "Developer sitting at a computer" ✗ — portraits are for agents, not skills
  "Abstract colorful splash without meaning" ✗ — too vague, no clear concept
  "Screenshot of a terminal window" ✗ — not an icon

Key rules:

• Style: flat vector / geometric / minimal — NOT photographic, NOT portraits
• Subject: abstract concept representing the skill's capability
• Format: square, clean background, recognizable at small sizes (64×64)
• Match skill function: git → branching, browser → window/globe, API → connector/plug

Image Size & Compression

Property	Value
Final resolution	512×512 (square)
File format	PNG (recommended for icons — crisp lines, transparency)
Max file size	≤30KB
Compression method	Python Pillow (pip3 install Pillow) resize + save

Compression procedure:

python3 -c "
from PIL import Image
img = Image.open('source.png')
img = img.resize((512, 512), Image.LANCZOS)
img.save('icon.png', 'PNG', optimize=True)
"

Always place images under an images/ subdirectory — NOT at the artifact root.

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")

Package Slug (name) — REQUIRED

The manifest name is the package slug: directory name, Hub URL segment (/@user/{slug}), SKILL.md frontmatter name, and share/publish id.

Rules (hard — invalid manifests are rejected on write / save / share):

• English kebab-case only: lowercase letters a-z, digits 0-9, hyphens -
• 2–64 characters; must start with a letter
• Pattern examples: git-changelog, web-scraper, pdf-summarizer
• NOT allowed: Chinese (网页抓取器), spaces, underscores, UPPERCASE, emoji, or empty
• Put the human-readable title (any language) in displayName, never in name
• Manifest name and SKILL.md frontmatter name must match exactly

User language	name (slug)	displayName
Chinese “网页抓取”	web-scraper	网页抓取
English “Git Changelog”	git-changelog	Git Changelog

If the user only gives a Chinese title, you invent an English kebab slug, set displayName to their title, and use the slug for ~/.markus/builder-artifacts/skills/{name}/.

Field Reference

Top-level fields

• type: Always "skill"
• name: Package slug — English kebab-case only (see Package Slug). Write/save/share reject Chinese or invalid slugs. Must match SKILL.md frontmatter name.
• 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 is listed in every agent's discoverable catalog as a foundational skill (e.g., Learning Habits). Full instructions are not auto-injected — agents activate via discover_tools({ name: [...] }) (Hermes progressive disclosure). Default is false.

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 a valid English kebab-case slug (see Package Slug). Never use Chinese as name. Invalid name → write/save/share fails.
• 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.