agent-building

# Agent Building This skill teaches you how to create Markus agent packages — self-contained directory-based artifacts that define an AI agent's identity, capabilities, constraints, and visual assets. ## Artifact Directory **CRITICAL**: Agent artifacts MUST be saved under this exact path — the Builder page, install system, and deliverable detection all depend on it: ``` ~/.markus/builder-artifacts/agents/{agent-name}/ ├── agent.json # Manifest (auto-created from your JSON output) ├── README.md # Public-facing overview for Hub/Builder (REQUIRED) ├── ROLE.md # Identity and system prompt (REQUIRED) ├── HEARTBEAT.md # Periodic self-check checklist (RECOMMENDED) ├── POLICIES.md # Constraints & guardrails (optional) ├── CONTEXT.md # Domain context & references (optional) └── images/ # Image assets (avatar, screenshots) └── avatar.jpg # Agent avatar/thumbnail image ``` **Do NOT write artifacts to `~/.markus/shared/`, your working directory, or any other location.** Only `~/.markus/builder-artifacts/agents/` is recognized by the system. When the user **installs** the artifact, files are deployed to `~/.markus/agents/{agentId}/role/`. The `ROLE.md` becomes the agent's system prompt — it IS the agent's identity, not an override of a template. ## Package Slug (`name`) — REQUIRED The manifest `name` is the **package slug**: directory name, Hub URL segment (`/@user/{slug}`), 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: `code-reviewer`, `paper-mentor`, `seo-auditor` - **NOT allowed**: Chinese (`智库研究团队`), spaces, underscores, UPPERCASE, emoji, or empty - Put the human-readable title (any language) in **`displayName`**, never in `name` | User language | `name` (slug) | `displayName` | |---|---|---| | Chinese "论文导师" | `paper-mentor` | `论文导师` | | English "Code Reviewer" | `code-reviewer` | `Code Reviewer` | If the user only gives a Chinese title, **you invent an English kebab slug** that captures the meaning, set `displayName` to their title, and use the slug for the directory path `~/.markus/builder-artifacts/agents/{name}/`. ## Two-Step Workflow Output the agent 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/agents/{name}/agent.json", ...)` for the manifest 2. `file_write` for each content file (ROLE.md, HEARTBEAT.md, …) 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**. ```json { "type": "agent", "name": "agent-name-kebab-case", "displayName": "Agent Display Name", "version": "1.0.0", "description": "What this agent does", "author": "", "category": "development | devops | management | productivity | general", "tags": ["tag1", "tag2"], "icon": "images/avatar.jpg", "thumbnail": "images/avatar.jpg", "screenshots": ["images/avatar.jpg"], "license": "MIT", "originalSource": "https://github.com/...", "dependencies": { "skills": ["skill-id-1", "skill-id-2"], "env": ["git", "node"] }, "agent": { "agentRole": "manager | worker", "llmProvider": "anthropic | openai | google | (empty for default)", "llmModel": "model name or empty for default", "temperature": 0.7 } } ``` After `agent.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/agents/{agent-name}/` (use the `name` from your JSON). **Write files in this order:** 1. **README.md** (REQUIRED) — The public-facing overview displayed on Markus Hub and the Builder detail page. This is what users see first when browsing artifacts. Write 2-4 paragraphs covering: - What this agent does and what problem it solves - Key capabilities and features - Example use cases or when to use this agent - Any requirements or setup notes 2. **ROLE.md** (REQUIRED) — The agent's primary identity document. **Before writing, read the existing base role template** via `file_read` (path shown in dynamic context) to understand expected depth and conventions. At least 5 substantive paragraphs covering: - Who this agent is (identity, personality, expertise) - Core responsibilities and capabilities - **Workflow with platform capabilities** — when and how to use `spawn_subagent` (focused subtasks), `background_exec` (long-running commands with auto-notifications), `shell_execute` (git/gh operations), `web_search`/`web_fetch` (research), `deliverable_create` (artifacts), `memory_save` (persistent knowledge) - For code-writing agents: workspace setup (git worktree for isolation), TDD, submit-for-review flow, file ownership rules - For review agents: review-then-merge workflow using `shell_execute` with `git merge` or `gh pr create/merge` - Output standards and quality criteria - Domain-specific knowledge and context 3. **HEARTBEAT.md** (RECOMMENDED) — Defines what the agent proactively checks every ~30 minutes via `HeartbeatScheduler`. **Without this file, the agent is purely reactive** — it will only respond to direct messages and task assignments, never proactively monitor its environment. Write a role-specific checklist: - Check mailbox for new messages and respond to urgent items - Review assigned tasks — update progress, unblock if possible - Check team announcements for new information - Role-specific patrol items (e.g., code agents: check build/CI status; review agents: check tasks awaiting review; managers: check team task board and unblock members) - Scan recent channel messages for anything requiring attention 4. **POLICIES.md** (recommended) — Safety constraints and guardrails: - What the agent should NOT do - Tool usage guidelines - Quality gates and review requirements 5. **CONTEXT.md** (optional) — Additional domain context, references, or knowledge. 6. **images/avatar.jpg** — Agent visual assets (see [Image Assets](#image-assets) section below). **Example file_write calls:** ``` file_write("~/.markus/builder-artifacts/agents/code-reviewer/README.md", "# Code Reviewer\n\nA meticulous code review agent that ensures code quality...\n\n## Features\n- Automated PR review...\n- Security vulnerability detection...\n\n## Use Cases\n- Add to any development team for automated code review") file_write("~/.markus/builder-artifacts/agents/code-reviewer/ROLE.md", "# Code Reviewer\n\nYou are **Code Reviewer** — an expert...\n\n## Responsibilities\n...\n\n## Workflow\n...\n\n## Output Standards\n...") file_write("~/.markus/builder-artifacts/agents/code-reviewer/HEARTBEAT.md", "# Heartbeat Checklist\n\n- [ ] Check mailbox for new messages\n- [ ] Check tasks awaiting review — prioritize by deadline\n- [ ] Review assigned tasks and update progress\n- [ ] Scan team channels for review requests") file_write("~/.markus/builder-artifacts/agents/code-reviewer/POLICIES.md", "# Policies\n\n- Only use shell_execute for read-only commands...\n- Always show file contents before overwriting...") ``` ## Image Assets Agent avatars are **digital employee portraits** — they should depict a person (realistic human style), not abstract icons, logos, or illustrations. Users should recognize the agent as a team member, not a mascot. ### Image Generation Use the `generate_image` tool to create agent portraits. Prompt style guide: ``` Good prompt (do this): "Professional headshot of a friendly male product manager in a business casual attire, warm blue tones, clean background, digital art style, realistic portrait" "Creative female content writer with glasses, warm orange tones, looking thoughtful, holding a notebook, realistic digital portrait, professional yet approachable" Bad prompt (don't do this): "Abstract icon of a roadmap with sticky notes" ✗ — user said "不知所云" "A laptop with writing bubbles floating above it" ✗ — not a person "Logo design for a content creator" ✗ — not a digital employee ``` Key prompt rules: - **Subject is always a person** — realistic digital portrait - **Match the role's personality** — PM = organized/strategic, Creator = creative/warm - **Use color palette** that aligns with the role (blue for analytical, orange for creative, green for growth) - **Background**: clean, professional, non-distracting - **Style**: `"realistic digital portrait", "professional headshot", "digital art style"` ### Image Size & Compression The `generate_image` tool typically outputs large images (e.g., 2048x2048, 400KB+). **Always compress before saving to the artifact directory.** Recommended specifications: | Property | Value | |:---------|:------| | **Final resolution** | 512×512 (square) | | **File format** | JPEG | | **Max file size** | ≤50KB | | **Compression method** | Python Pillow (`pip3 install Pillow`) resize + save | Compression procedure: ```python # Using Python Pillow python3 -c " from PIL import Image img = Image.open('source.jpg') img = img.resize((512, 512), Image.LANCZOS) img.save('avatar.jpg', 'JPEG', quality=85) " ``` Typical result: 2048×2048 (426KB) → 512×512 (19KB), saving ~96%. ### File Placement | File | Directory | Purpose | |:----|:----------|:--------| | `avatar.jpg` | `images/` | Agent avatar, used for both `icon` and `thumbnail` | | Additional screenshots | `images/` | Optional, for feature showcase | **Always** place images under an `images/` subdirectory — NOT at the artifact root. This follows the existing convention used by `paper-mentor`, `prompt-engineer`, and other agents. ### Local Path vs Hub CDN URL This is a critical distinction: | Phase | Field | Value | Where | |:------|:------|:------|:------| | **Local artifact (builder-artifacts/)** | `icon` | `"images/avatar.jpg"` | Relative path in agent.json | | **Local artifact (builder-artifacts/)** | `thumbnail` | `"images/avatar.jpg"` | Relative path in agent.json | | **Local artifact (builder-artifacts/)** | `screenshots` | `["images/avatar.jpg"]` | Relative paths in agent.json | | **Published to Hub** | `icon` | Emoji or CDN URL | Hub DB field (`hub_items.icon`) | | **Published to Hub** | `thumbnailUrl` | `"https://hub.markus.global/uploads/img_xxx.jpg"` | Hub DB field (`hub_items.thumbnail_url`) | | **Published to Hub** | `images` | `[{"url":"...","alt":"...","order":0}]` | Hub DB field (`hub_items.images`) | **Note:** Hub DB schema uses `thumbnailUrl` (not `thumbnail`), and `images` (not `screenshots`). The local artifact file uses `thumbnail` and `screenshots` for compatibility with the local install system. When publishing to Hub via API, map: - Local `thumbnail` → Hub `thumbnailUrl` - Local `screenshots` → Hub `images` (converted to `{url, alt, order}[]` format) ## Field Reference ### Top-level fields - **`type`**: Always `"agent"` - **`name`**: **Package slug** — English kebab-case only (see [Package Slug](#package-slug-name--required)). Invalid/save/share reject Chinese or invalid slugs. - **`displayName`**: Human-readable name, can be in any language (e.g., `"论文学习导师"`, `"Code Reviewer"`) - **`version`**: Semver (default `"1.0.0"`) - **`description`**: What this agent does (can be in any language) - **`category`**: One of `development`, `devops`, `management`, `productivity`, `general`, `marketing`, `engineering`, `product-management` - **`tags`**: Array of descriptive tags - **`icon`** (optional): Can be emoji OR image path. Emoji is lighter (zero network cost). Image path is visually richer. Both work in the Hub UI. Example: `"🚀"` or `"images/avatar.jpg"` - **`thumbnail`** (optional): Relative path to avatar image in artifact. Shows as large preview. Must be under `images/` directory. Example: `"images/avatar.jpg"` - **`screenshots`** (optional): Array of image paths for gallery/展示. Each path under `images/`. Example: `["images/avatar.jpg"]` - **`license`** (optional): License type, e.g. MIT, Apache-2.0. Example: `"MIT"`