@markus-global/cli 0.2.0

package/templates/skills/chrome-devtools/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: chrome-devtools
+description: Chrome DevTools browser automation via MCP - control a live Chrome browser
+---
+
+# Chrome DevTools Browser Automation
+
+You have access to a live Chrome browser via Chrome DevTools MCP tools (prefixed `chrome-devtools__`).
+This gives you full browser automation: navigation, clicking, typing, screenshots, JS evaluation,
+network inspection, and performance profiling.
+
+## When to use these tools
+
+Use Chrome DevTools tools when you need to:
+- Interact with web pages (click buttons, fill forms, navigate)
+- Test web applications in a real browser
+- Take screenshots of pages or elements
+- Inspect console logs, network requests, or page structure
+- Run Lighthouse audits or performance traces
+- Debug frontend issues with live DOM inspection
+
+Do NOT use these tools when `web_fetch` or `web_search` suffice (simple content retrieval or search).
+Chrome DevTools is for interactive browser sessions that require a real rendering engine.
+
+## Prerequisites
+
+The MCP server connects to the user's running Chrome via `--autoConnect` (Chrome 144+).
+
+**Setup steps:**
+1. Chrome version must be 144 or newer (146+ recommended).
+2. Open `chrome://inspect/#remote-debugging` in Chrome and enable remote debugging.
+3. On first MCP connection, Chrome will show a permission dialog — the user must click **Allow**.
+
+**Known limitation — frozen/suspended tabs cause connection timeout:**
+
+When Chrome has frozen or suspended tabs (common with Memory Saver or "Continue where you left off"),
+the MCP server may hang on the first tool call. This is a known upstream issue
+(puppeteer [#12808](https://github.com/puppeteer/puppeteer/issues/12808),
+chrome-devtools-mcp [#775](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/775)).
+
+If you encounter a tool call timeout, inform the user and suggest these steps (in order):
+1. **Upgrade Chrome to 146+** — contains a partial fix for frozen tab handling.
+2. **Disable Memory Saver** — go to `chrome://settings/performance` and turn off "Memory Saver"
+   so Chrome stops freezing inactive tabs.
+3. **Activate suspended tabs** — click on each unloaded tab to wake it up, especially tabs
+   restored after a Chrome restart.
+4. **Use a dedicated Chrome profile** — create a clean profile with few tabs for development use,
+   reducing the chance of frozen targets blocking the connection.
+
+## Tool reference
+
+### Navigation (6 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `chrome-devtools__navigate_page` | Navigate to a URL |
+| `chrome-devtools__list_pages` | List all open tabs/pages |
+| `chrome-devtools__new_page` | Open a new tab |
+| `chrome-devtools__close_page` | Close a tab |
+| `chrome-devtools__select_page` | Switch to a specific tab |
+| `chrome-devtools__wait_for` | Wait for selector, navigation, or network idle |
+
+### Input (9 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `chrome-devtools__click` | Click an element by selector |
+| `chrome-devtools__fill` | Clear and fill a form field (preferred over type_text) |
+| `chrome-devtools__fill_form` | Fill multiple form fields at once |
+| `chrome-devtools__type_text` | Type text character by character (use for contenteditable) |
+| `chrome-devtools__press_key` | Press keyboard keys (Enter, Tab, Escape, etc.) |
+| `chrome-devtools__hover` | Hover over an element |
+| `chrome-devtools__drag` | Drag from one element to another |
+| `chrome-devtools__handle_dialog` | Accept or dismiss browser dialogs (alert/confirm/prompt) |
+| `chrome-devtools__upload_file` | Upload a file to a file input element |
+
+### Inspection (6 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `chrome-devtools__take_screenshot` | Capture screenshot (full page or viewport) |
+| `chrome-devtools__take_snapshot` | Get page accessibility tree (best for finding elements) |
+| `chrome-devtools__evaluate_script` | Execute JavaScript in the page context |
+| `chrome-devtools__get_console_message` | Get a specific console message |
+| `chrome-devtools__list_console_messages` | List recent console messages |
+| `chrome-devtools__lighthouse_audit` | Run a Lighthouse audit |
+
+### Network (2 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `chrome-devtools__list_network_requests` | List captured network requests |
+| `chrome-devtools__get_network_request` | Get details of a specific request |
+
+### Performance (4 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `chrome-devtools__performance_start_trace` | Start a performance trace |
+| `chrome-devtools__performance_stop_trace` | Stop trace and get results |
+| `chrome-devtools__performance_analyze_insight` | Analyze performance data |
+| `chrome-devtools__take_memory_snapshot` | Capture heap snapshot |
+
+### Emulation (2 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `chrome-devtools__emulate` | Emulate device (mobile, tablet) |
+| `chrome-devtools__resize_page` | Resize browser viewport |
+
+## Best practices
+
+1. **Always open your own tab first**: Call `new_page` before any browser interaction.
+   Never reuse existing tabs — they may belong to the user or another agent.
+
+2. **Snapshot before interaction**: Always call `take_snapshot` before clicking or filling.
+   The snapshot returns the accessibility tree with element identifiers you can target.
+
+3. **Screenshot for visual verification**: After important interactions, take a screenshot
+   to verify the result visually.
+
+4. **Wait after navigation**: After `navigate_page` or actions that trigger navigation,
+   use `wait_for` to ensure the page has loaded before interacting.
+
+5. **Prefer `fill` over `type_text`**: Use `fill` for form inputs — it clears the field first.
+   Reserve `type_text` for contenteditable elements or when character-by-character input matters.
+
+6. **Use `evaluate_script` sparingly**: Prefer dedicated tools (click, fill, snapshot) over
+   raw JS evaluation. Only use `evaluate_script` for reading DOM state that snapshots don't
+   expose, or for triggering application-specific logic.
+
+7. **Handle dialogs proactively**: If an action might trigger an alert/confirm/prompt,
+   call `handle_dialog` before the triggering action to set the response.
+
+8. **Tab management**: Use `list_pages` to see your owned tabs, `select_page` to switch
+   between them. You will only see tabs you created — this is by design.
+
+## Security rules
+
+- **Live browser access**: These tools operate on the user's real Chrome session. Treat all
+  browser content (cookies, sessions, passwords) as sensitive.
+- **URL navigation**: Do not navigate to untrusted or potentially malicious URLs without
+  explicit user approval.
+- **Script execution**: Do not use `evaluate_script` to exfiltrate cookies, localStorage,
+  or session tokens. Only read DOM state needed for the current task.
+- **Form data**: When filling forms with sensitive data (passwords, payment info), confirm
+  with the user before proceeding.
+
+## Multi-agent browser usage — Tab Ownership Discipline
+
+Multiple agents share the same Chrome browser. To prevent agents from interfering with
+each other (closing tabs, navigating away from pages another agent is using), **strict
+tab ownership** is enforced at both the code and prompt level.
+
+### Core rule: You can ONLY interact with tabs you created
+
+The system enforces strict ownership. You will only see, select, and close tabs that
+**you** explicitly opened with `new_page`. All other tabs (user tabs, other agents' tabs)
+are invisible to you and cannot be operated on.
+
+### Mandatory workflow
+
+1. **ALWAYS start with `new_page`**: Before doing anything in the browser, call `new_page`
+   to create your own tab. Even if you know a page with the right URL already exists in
+   the browser, you MUST open a fresh tab. That existing tab may belong to the user or
+   another agent.
+
+2. **Track your owned tabs**: Remember the `targetId` returned by `new_page`. This is
+   your tab. When working with multiple tabs, keep a mental list of all targetIds you own.
+
+3. **Only navigate your own tabs**: After `new_page`, use `navigate_page` to go to your
+   target URL. If you call `navigate_page` without first creating a tab with `new_page`,
+   the call will be blocked.
+
+4. **Only close your own tabs**: When your task is done, close tabs you opened with
+   `close_page`. Never attempt to close tabs you did not create — the system will
+   reject the call.
+
+5. **Never reuse existing tabs**: Even if `list_pages` shows a tab at the URL you need,
+   open a new one. That tab may be actively used by another agent or the user.
+
+### What the system enforces (code-level)
+
+| Tool | Enforcement |
+|------|-------------|
+| `new_page` | Creates a tab and registers it as yours |
+| `list_pages` | Only returns tabs you created (all others are hidden) |
+| `select_page` | Blocked unless the target tab is one you created |
+| `close_page` | Blocked unless the target tab is one you created |
+| `navigate_page` | Blocked if you have no owned tabs (must call `new_page` first) |
+
+### Shared state warning
+
+- **Cookies and login sessions are shared** across all agents (same Chrome instance).
+  If one agent logs out of a site, other agents lose that session too.
+- Avoid actions that affect global browser state (clearing cookies, changing Chrome
+  settings, closing all tabs) unless the task explicitly requires it.
+
+### Example: correct multi-agent workflow
+
+```
+Agent A:                              Agent B:
+1. new_page → gets tab T1             1. new_page → gets tab T2
+2. navigate_page T1 → localhost:3000  2. navigate_page T2 → localhost:3000
+3. (test feature X on T1)             3. (test feature Y on T2)
+4. close_page T1                      4. close_page T2
+```
+
+Both agents work on the same URL but in separate tabs without interference.
+
+## Common workflows
+
+### Web testing
+```
+1. new_page → create your own tab (remember targetId)
+2. navigate_page → target URL
+3. wait_for → page loaded
+4. take_snapshot → understand page structure
+5. click / fill / press_key → interact with elements
+6. take_screenshot → verify result
+7. close_page → clean up when done
+```
+
+### Form automation
+```
+1. new_page → create your own tab
+2. navigate_page → form URL
+3. take_snapshot → identify form fields
+4. fill_form → fill all fields at once
+5. click → submit button
+6. wait_for → response/redirect
+7. take_screenshot → confirm submission
+8. close_page → clean up when done
+```
+
+### Debugging frontend issues
+```
+1. new_page → create your own tab
+2. navigate_page → problematic page
+3. list_console_messages → check for errors
+4. list_network_requests → check for failed requests
+5. evaluate_script → inspect specific DOM state
+6. take_screenshot → capture visual state
+7. close_page → clean up when done
+```
+
+### Performance analysis
+```
+1. new_page → create your own tab
+2. navigate_page → target page
+3. performance_start_trace
+4. (perform user actions that need profiling)
+5. performance_stop_trace → get trace data
+6. performance_analyze_insight → interpret results
+7. lighthouse_audit → comprehensive audit
+8. close_page → clean up when done
+```

package/templates/skills/chrome-devtools/skill.json

@@ -0,0 +1,21 @@
+{
+  "type": "skill",
+  "name": "chrome-devtools",
+  "displayName": "Chrome DevTools",
+  "version": "1.0.1",
+  "description": "Chrome DevTools browser automation - control a live Chrome browser (navigate, click, type, screenshot, evaluate JS, inspect network, performance profiling)",
+  "author": "markus",
+  "category": "browser",
+  "tags": ["browser", "chrome", "devtools", "automation", "testing", "mcp"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "requiredPermissions": ["browser", "network"],
+    "isolation": "per-agent",
+    "mcpServers": {
+      "chrome-devtools": {
+        "command": "npx",
+        "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"]
+      }
+    }
+  }
+}

package/templates/skills/markus-admin-cli/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: markus-admin-cli
+description: System administration via markus CLI — system controls, audit, users, settings, gateway.
+---
+
+# System Administration via CLI
+
+Administrative operations through `shell_execute` with `markus admin` commands. Always use `--json` for parseable output.
+
+## System Controls
+
+```bash
+markus admin system status --json
+markus admin system version --json
+markus admin system update
+markus admin system update --dry-run
+markus admin system pause-all --reason "Deploying updates"
+markus admin system resume-all
+markus admin system emergency-stop
+markus admin system storage --json
+markus admin system orphans --json
+markus admin system announce --title "Maintenance" --content "Downtime at 2am" --priority high
+markus admin system policy --json
+markus admin system policy --set --body '{"defaultApproval":"manager"}'
+```
+
+| Command | Key Options |
+|---------|-------------|
+| `admin system status` | |
+| `admin system version` | Shows current version, git info, and whether updates are available |
+| `admin system update` | `--dry-run` (preview without applying). Pulls latest code, installs deps, rebuilds |
+| `admin system pause-all` | `--reason` |
+| `admin system resume-all` | |
+| `admin system emergency-stop` | |
+| `admin system storage` | |
+| `admin system orphans` | |
+| `admin system announce` | `--title` `--content` `--priority` `--type` `--expires-at` |
+| `admin system policy` | `--set <json>` (update mode) |
+
+**Update workflow**: When updating the platform, always: (1) confirm with the user, (2) pause all agents first (`pause-all`), (3) run `update`, (4) restart the service (`markus start`), (5) resume agents (`resume-all`).
+
+## Audit (nested under admin system)
+
+```bash
+markus admin system audit log --json --limit 50
+markus admin system audit log --type llm_request --agent-id agt_xxx
+markus admin system audit summary --json
+markus admin system audit tokens --json
+```
+
+## Users
+
+```bash
+markus admin user list --json
+markus admin user add --name "John" --role admin --email john@example.com
+markus admin user delete usr_xxx
+```
+
+## API Keys
+
+```bash
+markus admin key list --json
+markus admin key create --name "CI Key"
+markus admin key delete key_xxx
+```
+
+## Roles
+
+```bash
+markus admin role list --json
+markus admin role get developer --json
+```
+
+## Templates
+
+```bash
+markus admin template list --json
+markus admin template get Developer --json
+markus admin template instantiate --template-id Developer --name "New Agent" --org-id default
+```
+
+## Builder Artifacts
+
+```bash
+markus admin builder list --json
+markus admin builder get agent my-agent --json
+markus admin builder install agent my-agent
+markus admin builder uninstall agent my-agent
+```
+
+## Settings
+
+```bash
+markus admin settings llm --json
+markus admin settings env-models --json
+markus admin settings oauth-status --json
+```
+
+## Gateway (External Agent Access)
+
+```bash
+markus admin gateway info --json
+markus admin gateway register --agent-id ext_001 --agent-name "CI Bot" --org default
+markus admin gateway auth --agent-id ext_001 --org default --secret <secret>
+markus admin gateway message --text "Status update" --token <bearer-token>
+markus admin gateway status --token <bearer-token>
+markus admin gateway manual --token <bearer-token>
+markus admin gateway team --token <bearer-token>
+```
+
+## External Agents
+
+```bash
+markus admin external-agent list --json
+markus admin external-agent register --name "CI Bot" --type ci
+markus admin external-agent delete ext_xxx
+```
+
+## Permissions Note
+
+Most admin commands require owner or admin role. Agent-level operations require the agent to be part of your organization.

package/templates/skills/markus-admin-cli/skill.json

@@ -0,0 +1,14 @@
+{
+  "type": "skill",
+  "name": "markus-admin-cli",
+  "displayName": "Markus Admin CLI",
+  "version": "1.0.0",
+  "description": "System administration via markus CLI — system controls, audit, users, settings, gateway.",
+  "author": "markus",
+  "category": "platform",
+  "tags": ["cli", "admin", "governance", "audit", "settings"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "alwaysOn": false
+  }
+}

package/templates/skills/markus-agent-cli/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: markus-agent-cli
+description: Manage agents via markus CLI — lifecycle, messaging, config, memory, skills.
+---
+
+# Agent Management via CLI
+
+Operate agents through `shell_execute` with `markus agent` commands. Always use `--json` for parseable output.
+
+## Quick examples
+
+```bash
+# List all agents
+markus agent list --json
+
+# Get agent details
+markus agent get agt_xxx --json
+
+# Create an agent
+markus agent create --name "Alice" --role developer --team team_xxx
+
+# Start / stop agents
+markus agent start agt_xxx
+markus agent stop agt_xxx
+
+# Send a message
+markus agent message agt_xxx --text "Please review the API changes"
+
+# Update config
+markus agent config agt_xxx --skills "self-evolution,chrome-devtools"
+
+# View memory
+markus agent memory agt_xxx --json
+
+# Manage skills
+markus agent skill-add agt_xxx --skill-name chrome-devtools
+markus agent skill-remove agt_xxx --skill-name chrome-devtools
+
+# Trigger heartbeat or daily report
+markus agent heartbeat agt_xxx
+markus agent daily-report agt_xxx
+
+# Sync role from template
+markus agent role-sync agt_xxx
+```
+
+## Command Reference
+
+| Command | Key Options |
+|---------|-------------|
+| `agent list` | |
+| `agent get <id>` | |
+| `agent create` | `--name` (required) `--role` (required) `--org` `--team` `--agent-role` `--skills` |
+| `agent delete <id>` | `--purge` |
+| `agent start <id>` | |
+| `agent stop <id>` | |
+| `agent message <id>` | `--text` (required) `--sender` `--session` |
+| `agent chat <id>` | Interactive REPL mode |
+| `agent config <id>` | `--name` `--agent-role` `--skills` `--heartbeat` |
+| `agent memory <id>` | |
+| `agent files <id>` | |
+| `agent skill-add <id>` | `--skill-name` (required) |
+| `agent skill-remove <id>` | `--skill-name` (required) |
+| `agent activities <id>` | `--type` `--limit` |
+| `agent heartbeat <id>` | |
+| `agent daily-report <id>` | |
+| `agent role-sync <id>` | |

package/templates/skills/markus-agent-cli/skill.json

@@ -0,0 +1,14 @@
+{
+  "type": "skill",
+  "name": "markus-agent-cli",
+  "displayName": "Markus Agent CLI",
+  "version": "1.0.0",
+  "description": "Manage agents via markus CLI — lifecycle, messaging, config, memory, skills.",
+  "author": "markus",
+  "category": "platform",
+  "tags": ["cli", "agents", "lifecycle"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "alwaysOn": false
+  }
+}

package/templates/skills/markus-cli/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: markus-cli
+description: Core knowledge for operating the Markus platform via CLI. Prerequisite for domain-specific markus-*-cli skills.
+---
+
+# Markus CLI
+
+The `markus` command-line tool lets you operate the Markus platform programmatically.
+Use it via `shell_execute` to manage agents, projects, tasks, teams, and more.
+
+## How to invoke
+
+Use `markus` via `shell_execute`. The binary is automatically available in PATH — either from npm global install (`npm install -g @markus-global/cli`) or injected by the server at startup in source-dev mode.
+
+```bash
+markus agent list --json
+markus project task get tsk_abc123 --json
+markus admin system status --json
+```
+
+## Prerequisites
+
+- The Markus server must be running (started via `markus start`).
+- `markus start` auto-detects first run and initializes everything (DB, config wizard).
+- The CLI connects to `http://localhost:8056` by default. Override with `--server <url>` or `MARKUS_API_URL`.
+- For authenticated access use `--api-key <key>` or `MARKUS_API_KEY`.
+
+## Output format
+
+**Always use `--json` when parsing results programmatically.** Without `--json`, output is human-readable tables.
+
+```bash
+# Machine-readable — use this in automation
+markus agent list --json
+
+# Human-readable table
+markus agent list
+```
+
+## Platform Info
+
+- **Website**: https://www.markus.global/
+- **GitHub**: https://github.com/markus-global/markus
+
+## Command structure
+
+Commands follow the pattern: `markus <domain> [sub] <action> [id] [options]`
+
+```bash
+markus agent list                        # List agents
+markus project list --json               # List projects
+markus project task create --title "..."  # Create a task
+markus admin system status               # System health
+markus admin system version --json       # Check version and updates
+markus <domain> --help                   # See all subcommands
+```
+
+## Command hierarchy
+
+| Command | Description | Skill |
+|---------|-------------|-------|
+| `start` | Start server (auto-init on first run) | — |
+| `agent` | Agent lifecycle, config, memory, skills | markus-agent-cli |
+| `team` | Team CRUD, members, lifecycle | markus-team-cli |
+| `skill` | Skill registry, install, scaffold | markus-skill-cli |
+| `project` | Project CRUD | markus-project-cli |
+| `project task` | Task CRUD, lifecycle, subtasks, comments | markus-project-cli |
+| `project requirement` | Requirement CRUD, approval | markus-project-cli |
+| `project deliverable` | Deliverable CRUD | markus-project-cli |
+| `project report` | Report generation, usage stats | markus-project-cli |
+| `project review` | Code / task reviews | markus-project-cli |
+| `project approval` | HITL approvals | markus-project-cli |
+| `admin` | Platform administration & system controls | markus-admin-cli |
+| `admin system` | Global controls, governance, storage, version, update | markus-admin-cli |
+| `admin system audit` | Audit log and summary | markus-admin-cli |
+| `admin user` | Human user management | markus-admin-cli |
+| `admin key` | API key management | markus-admin-cli |
+| `admin role` | Role templates | markus-admin-cli |
+| `admin template` | Agent/team templates | markus-admin-cli |
+| `admin builder` | Builder artifacts | markus-admin-cli |
+| `admin gateway` | External agent gateway | markus-admin-cli |
+| `admin settings` | LLM and platform settings | markus-admin-cli |
+| `admin external-agent` | External agent registration | markus-admin-cli |
+
+## Installation & Update
+
+```bash
+# Install via npm (recommended)
+npm install -g @markus-global/cli
+
+# Or one-line install
+curl -fsSL https://markus.global/install.sh | bash
+
+# Check current version
+markus admin system version --json
+
+# Update to latest (npm mode)
+npm update -g @markus-global/cli
+
+# Update to latest (source mode — pulls from GitHub, installs deps, rebuilds)
+markus admin system update
+
+# Preview update without making changes
+markus admin system update --dry-run
+```
+
+**Always confirm with the user before updating** — it requires a service restart which interrupts running agents.
+
+## Tips
+
+- Always use `--json` and parse the JSON output for reliable automation.
+- When creating tasks, always specify `--project-id` if projects exist.
+- Use `markus <domain> --help` to discover available subcommands and options.

package/templates/skills/markus-cli/skill.json

@@ -0,0 +1,14 @@
+{
+  "type": "skill",
+  "name": "markus-cli",
+  "displayName": "Markus CLI",
+  "version": "1.0.0",
+  "description": "Core knowledge for operating the Markus platform via CLI commands. Prerequisite for all markus-*-cli skills.",
+  "author": "markus",
+  "category": "platform",
+  "tags": ["cli", "platform", "management", "api"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "alwaysOn": false
+  }
+}

package/templates/skills/markus-hub-connector/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: markus-hub-connector
+description: Search, download, and publish agents/teams/skills on Markus Hub
+---
+
+# Markus Hub Connector
+
+You have access to the Markus Hub community marketplace via MCP tools (prefixed `markus-hub__`).
+This lets you search for shared packages, download them locally, publish user creations, and manage published items.
+
+## When to use these tools
+
+Use Hub tools when the user wants to:
+- Find agents, teams, or skills shared by the community
+- Download a package from Hub to try locally
+- Share/publish a builder artifact to Hub
+- Check what they've published on Hub
+
+Do NOT use these tools for local skill/agent management — those are separate operations.
+
+## Authentication
+
+Hub operations that modify data (download, publish, my_items) require the user to be logged in to Markus Hub via the web UI. If a tool returns an authentication error, tell the user to log in to Hub from the Markus web interface first.
+
+The login state is synced automatically — no manual token setup is needed.
+
+## Tool reference
+
+| Tool | Purpose | Auth required |
+|------|---------|:---:|
+| `markus-hub__hub_search` | Search Hub for packages by keyword, type, category | No |
+| `markus-hub__hub_download` | Download a package to local builder-artifacts | Yes |
+| `markus-hub__hub_publish` | Publish a local artifact to Hub | Yes |
+| `markus-hub__hub_my_items` | List the user's published items | Yes |
+
+## Common workflows
+
+### Finding and downloading a skill
+```
+1. markus-hub__hub_search → query="code review", type="skill"
+2. Review results, confirm with user which one to download
+3. markus-hub__hub_download → id="<item_id>"
+4. Tell user to install from Builder page
+```
+
+### Publishing a builder artifact
+```
+1. markus-hub__hub_publish → directory="~/.markus/builder-artifacts/skills/my-skill"
+   (auto-reads manifest + files from directory)
+2. Share the Hub URL with the user
+```
+
+### Checking published items
+```
+1. markus-hub__hub_my_items → see all published packages
+2. Report status to user
+```
+
+## Best practices
+
+1. **Always confirm before publishing**: Show the user what will be published (name, description, files) before calling `hub_publish`.
+2. **Use directory mode for publish**: When publishing a local artifact, pass the `directory` parameter — it auto-reads the manifest and all files.
+3. **Guide on auth errors**: If a tool returns an auth error, tell the user to log in via the Hub icon in the Markus web UI.
+4. **Search before download**: Help the user find the right package before downloading.