Agents

Agent (AI Agent / Digital Worker) is the unit that does the work in Markus. The platform formula: Agent = LLM + Harness + Learning Loop — an executable worker driven by an LLM, wrapped in a runtime (tools / memory / attention) plus a learning loop. This page explains it end to end: what an Agent is, how an Agent Package is built (manifest / ROLE.md / skill binding / avatar), and the rules for publishing to the Hub. ← Back to Assets · 中文原版


1. Concept Overview

ConceptDescription
AgentAn AI agent: a self-identity ROLE.md + a set of tools + memory and heartbeat, assignable to do work
Agent PackageA reusable, Hub-publishable, self-contained directory artifact defining the Agent’s identity / capabilities / constraints / visual assets
Manifest (agent.json)Package metadata: name, version, dependencies, LLM config, role
ROLE.mdThe Agent’s identity document = system prompt, defining “who it is, how it works”
Skill bindingDeclares the skills this Agent depends on via dependencies.skills

Key distinction: creating an Agent package (writing into builder-artifacts — just a reusable artifact) ≠ installing / hiring (deploying into the organization, consuming resources, joining a team). Never install automatically — only when the user explicitly says install / deploy / hire.


2. Artifact Directory

The system only recognizes this one path — the Builder page, the install system, and deliverable detection all depend on it:

~/.markus/builder-artifacts/agents/{agent-name}/   ← {name} must be a valid slug
├── agent.json       # config (manifest; write with file_write as JSON)
├── README.md        # public description (Hub / Builder display, REQUIRED)
├── ROLE.md          # identity & system prompt (REQUIRED — the identity itself)
├── HEARTBEAT.md     # periodic self-check checklist (RECOMMENDED)
├── POLICIES.md      # constraints & guardrails (optional)
├── CONTEXT.md       # domain context & reference material (optional)
└── images/
    └── avatar.jpg   # Agent avatar (digital employee portrait)

Do not write to ~/.markus/shared/, the current working directory, or anywhere else — only builder-artifacts/agents/ is recognized by the system. After installation, files are deployed to ~/.markus/agents/{agentId}/role/, where ROLE.md becomes the Agent’s system prompt — it is the Agent’s identity, not an override of a template.


3. Two-Step Workflow

Manifest first, then content files. This rule applies to every mode (chat / task / A2A): JSON code blocks in replies do not create files automatically, and never inline file content into JSON.

  1. file_write("~/.markus/builder-artifacts/agents/{name}/agent.json", ...) — write the manifest (metadata only).
  2. file_write the content files in order: README.md → ROLE.md → HEARTBEAT.md → POLICIES.md → CONTEXT.md → images/avatar.jpg.

4. Manifest (agent.json) Fields

{
  "type": "agent",
  "name": "code-reviewer",              // slug, kebab-case English letters/numbers/hyphens required
  "displayName": "Code Reviewer",       // human-readable name (any language)
  "version": "1.0.0",
  "description": "What this agent does",
  "author": "",
  "category": "development",            // development | devops | management | productivity | general | marketing | engineering | product-management
  "tags": ["review", "code-quality"],
  "icon": "images/avatar.jpg",          // emoji or relative image path
  "thumbnail": "images/avatar.jpg",
  "screenshots": ["images/avatar.jpg"],
  "license": "MIT",
  "originalSource": "https://github.com/...",
  "dependencies": { "skills": ["coding-tools"], "env": ["git", "node"] },
  "agent": { "agentRole": "worker", "llmProvider": "anthropic", "llmModel": "", "temperature": 0.7 }
}

Package Name (Slug) — Hard Rule

name is the package slug: simultaneously the directory name, the Hub URL segment (/@user/{slug}), and the share/publish ID. Invalid slugs are rejected on write / save / share:

  • English kebab-case only: lowercase a-z, digits 0-9, hyphens -; 2–64 characters, must start with a letter.
  • Not allowed: Chinese, spaces, underscores, uppercase, emoji, empty.
  • Put the human-readable title (may be Chinese) in displayName, never in name. When the user only gives a Chinese name, invent a semantically fitting English kebab slug and keep the original name in displayName.
User languagename (slug)displayName
论文导师 (Chinese)paper-mentor论文导师
”Code Reviewer” (English)code-reviewerCode Reviewer

Field Quick Reference

FieldDescriptionNotes
categoryCategoryLimitation: restricted to the field enum
dependencies.skillsArray of skill IDs this agent depends onAssign proactively; don’t leave empty
dependencies.envRequired CLI toolse.g. ["git", "node"]
agent.agentRoleworker or managermanager coordinates / assigns / reviews
agent.llmProvider / llmModel / temperatureLLM configEmpty = system default; temperature: 0.7 general, 0.3–0.5 precise, 0.8–1.0 creative
roleNameNot neededThe Agent’s identity is fully defined by ROLE.md; unless you want to inherit a built-in role template’s default tools (rare), don’t add it

⚠️ Manifest validation: all top-level field types must be correct (author is a string, not an object; tags is a string array; version is semver; description is a string). The system validates on write and rejects invalid manifests.


5. ROLE.md Is the Identity (+ HEARTBEAT / POLICIES)

Once installed, ROLE.md becomes the Agent’s system prompt — the source of its distinctiveness — requiring at least 5 substantive paragraphs; a paragraph of boilerplate is useless. Cover: identity (who I am / personality / expertise), core responsibilities, a workflow that works with platform capabilities (when to spawn_subagent to split subtasks, background_exec for long commands, shell_execute for git/gh, web_search / web_fetch for research, deliverable_create for outputs, memory_save for persistent memory), output standards and quality gates, and domain knowledge. For coding Agents: workspace isolation (git worktree), TDD, review-then-merge; for review Agents: the review → merge flow with git merge / gh pr create|merge.

Companion files:

  • README.md (REQUIRED): the public-facing display for Hub/Builder — 2–4 paragraphs: what it does, what problem it solves, core capabilities, usage scenarios, required environment.
  • HEARTBEAT.md (RECOMMENDED): defines what to actively patrol roughly every 30 minutes (check the mailbox for urgent items, recheck assigned tasks, scan team announcements, role-specific patrol items). Without it the Agent is only passive — it never proactively monitors its environment.
  • POLICIES.md: safety guardrails — what not to do, tool usage rules, quality gates. Safety comes from POLICIES constraints, not from removing tools — all Agents can use all built-in tools by default.

6. Skill Binding (dependencies.skills)

An Agent binds skills through dependencies.skills:

"dependencies": { "skills": ["coding-tools", "chrome-devtools"] }
  • Skills are reusable capability packages (see Skills); after installation the Agent loads them progressively via discover_tools — full instructions are not stuffed into the system prompt at spawn time.
  • Don’t invent skill IDs: only use skills that actually exist in the dynamic context; when a skill is available, don’t leave it empty.

7. Visual Assets (avatar)

An Agent avatar is a digital employee portrait — realistic human style, not an abstract logo/illustration. Users should treat Agents as team members, not mascots. The subject must always be a person: match the character’s personality (PM = organized/strategic, creator = creative/approachable), colors that fit the role (blue = analytical, orange = creative, green = growth), clean professional background.

PropertyValue
Resolution512×512 (square)
FormatJPEG
Max size≤50KB
CompressionPython Pillow resize + save

Example prompt: Professional headshot of a friendly male engineering lead in business casual, warm blue tones, clean background, realistic digital portrait. Always compress (generate_image often outputs 400KB+ → 512×512/≤50KB, saving ~96%). Images go in the images/ subdirectory.

Local vs Hub field mapping: local artifacts use relative paths thumbnail / screenshots; when published to the Hub they map to thumbnailUrl / images ({url,alt,order}[]). Publishing details: Markus Hub →.


8. Create ≠ Install (Red Line)

Creating an artifact ≠ installing/deploying. Creating only writes files to builder-artifacts/; installing deploys a real Agent into the active organization (consuming resources, joining a team). Never install automatically unless the user explicitly says “install” / “deploy” / “hire” — then use package_install / hub_install. After creating: tell the user it was created and saved, that visual assets are included, that it can be installed (Builder page or package_install), and that it can be iterated on (just update the files).


9. Build Rules Quick Reference

  • Don’t invent Skill IDs — only use values present in the dynamic context; don’t default skills to [].
  • Don’t stuff file content into JSON — always file_write real files.
  • Don’t write to ~/.markus/shared/ or the working directory — always ~/.markus/builder-artifacts/agents/{name}/.
  • name must be a valid English kebab-case slug; top-level field types must be correct (validated on write).
  • Avatars must be realistic portraits / digital employee portraits; always compress images (≤50KB); images go in the images/ subdirectory.
  • ROLE.md: at least 5 substantive paragraphs; temperature: 0.7 general, 0.3–0.5 precise, 0.8–1.0 creative.

10. Next Steps

  • Orchestrate multiple Agents into a team → Teams.
  • Give Agents reusable capabilities → Skills.
  • Publish and ship the package to the Hub marketplace → Markus Hub.