Skip to main content
Agent skill

Maxxing Extension

Build a Harness Maxxing extension - a dashboard widget (a Card with stats, lists, charts, or a free-form HTML widget such as a game or canvas), a full page with its own API, or a custom view of the Overview of the Agents page - in <workspace>/extensions/<id>/. Use when the user asks for a new widget, a dashboard card, a mini-game, a custom page, an integration shown in the UI, or to fix an existing extension. Always the first choice before touching the product code.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/maxxing-extension && curl -fsSL 'https://raw.githubusercontent.com/makushingu/harness-maxxing/main/skills/maxxing-extension/SKILL.md' -o ~/.claude/skills/maxxing-extension/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Maxxing Extension when an AI agent needs a reusable SKILL.md workflow for this job: Build a Harness Maxxing extension - a dashboard widget (a Card with stats, lists, charts, or a free-form HTML widget such as a game or canvas), a full page with its own API, or a custom view of the Overview of the Agents page - in <workspace>/extensions/<id>/. Use when the user asks for a new widget, a dashboard card, a mini-game, a custom page, an integration shown in the UI, or to fix an existing extension. Always the first choice before touching the product code.

When not to use it

Skip Maxxing Extension when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/maxxing-extension && curl -fsSL 'https://raw.githubusercontent.com/makushingu/harness-maxxing/main/skills/maxxing-extension/SKILL.md' -o ~/.claude/skills/maxxing-extension/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/maxxing-extension/SKILL.md. For a shared project, commit the folder at .claude/skills/maxxing-extension/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Maxxing Extension skill for this task: Use Maxxing Extension when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Extensions (widgets & pages)

Extensions live in `<workspace>/extensions/<id>/` (workspace from `maxxing status`, here `{{WORKSPACE}}`). Product updates never touch them and the memory backup includes them.

- **widget**: `manifest.json` + `api.py` with `card(ctx)` returning a **Card** (JSON). The UI draws it with the built-in design system - no HTML/CSS to write, consistent look guaranteed. - **HTML widget**: `manifest.json` (`"type": "widget"`, optional `"height"`) + `widget.html` (one self-contained file) + optional `api.py` with `handle(...)`. For games, canvas, custom drawings: anything a Card cannot show. Drawn in a sandboxed frame (see below). - **page**: `manifest.json` + `page.js` (ES module, `mount(el, ctx)`) + optional `api.py` with `handle(ctx, method, path, query, body)` served at `/api/ext/<id>/<path>`. Listed under "Extensions" in the sidebar; the user can pin it to get its own entry. - **Overview view** (Agents page): `manifest.json` (`"type": "view"`, `"agents_view": {...}`) + `agents-view.html`. Listed in the view menu of the Overview; draws the agents its own way. See "Overview view" below.

## Built-in Shopify widget "Connect my Shopify store" needs no extension: guide the user to create a custom app in Shopify admin (Settings → Apps and sales channels → Develop apps → Create an app → Admin API scopes `read_orders` → Install → reveal the `shpat_…` token) and to add `SHOPIFY_STORE` (`myshop.myshopify.com`) and `SHOPIFY_ADMIN_TOKEN` in Settings → Keys. For more shop figures (products, ads, other platforms), build extra widgets: they sit next to it on the dashboard.

## Which kind? (and never the product code) | The user wants… | Build | |---|---| | numbers, lists, charts, status from some data source | widget with `card(ctx)` | | a mini-game, a canvas, an interactive or custom-drawn card | HTML widget | | a whole screen (form, board, editor, report) | page | | another look for the Overview of the Agents page ("Create my custom view") | Overview view | | to change how the product itself behaves (a server rule, a CLI command…) and no extension can do it | a **core customization**: skill `maxxing-customize` - never edit the code directory without it |

Extensions survive every update untouched. Say so to the user: they never need to wait for the authors to add something an extension can do.

## Rules - `id`: lowercase slug `^[a-z0-9][a-z0-9-]{0,47}$`, same as the folder name. Reserved: `activity tasks day crons server backup telegram shopify usage customize`. - `name`: a string, or `{"en": "...", "fr": "..."}` to follow the UI language. - `api`: always write `"api": 1` in the manifest (the extension contract version this extension is written for; the update preflight uses it to tell the user before a new version stops supporting it). - `icon`: an icon name of the app's lucide set (`gauge`, `chart-line`, `shopping-cart`, `server`, `rss`, `users`, `receipt`, `calendar-days`, `package`, `star`…; the full list is `ICONS` in `<code dir>/web/src/components/ui/icon.tsx`, an unknown name shows a puzzle piece). - **No emoji in the UI** (titles, list items, buttons): use icons - the Card list `icon`, `ctx.icon()` in a page. - `api.py` runs inside the server process: **stdlib only** (urllib, json, sqlite3…), short timeouts (≤ 10 s), no threads left behind, never print secrets. It is called in a worker thread. - Secrets: the user stores them in Settings -> Keys; read them with `ctx["secret"]("NAME")` (returns None when missing -> return a Card saying which key to add). Never hard-code a token. - Persistent data: `ctx["state_dir"]` (a folder reserved for this extension). - `ctx` = `{"id", "workspace", "state_dir", "secret": fn(name), "config": {"timezone", "language", "public_url"}}`. - Widget results are cached `ttl` seconds (manifest, default 300); the card's refresh button forces it.

## Card schema ``` Card = {title?, status?: "ok"|"warn"|"error", link?: "/route or https://…", blocks: [Block], updated?: unix} Block = {type:"stat", label, value, hint?, delta?, tone?: "ok"|"warn"|"error"} | {type:"stats", items:[stat…]} | {type:"list", items:[{title, subtitle?, value?, href?, status?, icon?}], empty?: "text when no items", grid?: true} grid = tiles side by side (shortcuts, examples) icon = icon name (as the manifest), accent-coloured | {type:"chart", kind:"bar"|"line", series:[{name, points:[[x, y], …]}], unit?} | {type:"table", columns:[str], rows:[[cell, …]]} | {type:"progress", label, value, max, hint?} | {type:"markdown", text} | {type:"timeline", start, end, now?, lanes:[{name, sub?, color?, href?, dense?, events:[{at, state?: "ok"|"error"|"running"|"planned", label?}]}]} ``` (`timeline`: unix seconds; one row per lane on a start..end axis - bookings, deliveries, shifts, runs.) Unknown block types are dropped; the card must be JSON-serialisable.

## Minimal widget - `extensions/disk-usage/` `manifest.json` ```json {"id": "disk-usage", "name": "Disk usage", "type": "widget", "icon": "hard-drive", "version": "1.0.0", "span": 1, "ttl": 60} ``` `api.py` ```python import shutil

def card(ctx): rows = [] worst = 0 for mount in ("/", "/var"): du = shutil.disk_usage(mount) pct = round(100 * (du.total - du.free) / du.total) worst = max(worst, pct) rows.append({"type": "progress", "label": mount, "value": pct, "max": 100, "hint": f"{du.free / 1e9:.1f} GB free"}) return {"title": "Disk usage", "status": "error" if worst > 95 else "warn" if worst > 85 else "ok", "blocks": [{"type": "stat", "label": "Fullest volume", "value": f"{worst}%"}, *rows]} ```

## Minimal page - `extensions/notes-board/` `manifest.json` ```json {"id": "notes-board", "name": "Notes board", "type": "page", "icon": "sticky-note", "version": "1.0.0"} ``` `api.py` ```python import json import time from pathlib import Path

def _file(ctx): return Path(ctx["state_dir"]) / "notes.json"

def handle(ctx, method, path, query, body): f = _file(ctx) notes = json.loads(f.read_text()) if f.exists() else [] if method == "GET" and path == "notes": return {"notes": notes} if method == "POST" and path == "notes": text = str((body or {}).get("text", "")).strip()[:500] if text: notes.insert(0, {"text": text, "at": time.time()}) tmp = f.with_suffix(".tmp") tmp.write_text(json.dumps(notes[:200])) tmp.replace(f) return {"notes": notes} return {"error": "not_found", "message": f"{method} {path}"} ``` `page.js` ```js export function mount(el, ctx) { el.innerHTML = ` <div class="ui-page" style="max-width:640px"> <h1 class="ui-h1">Notes board</h1> <form class="ui-row"> <input class="ui-input" name="text" placeholder="New note" style="flex:1"> <button class="ui-btn">Add</button> </form> <ul class="ui-list"></ul> <p class="ui-muted" hidden>No note yet: write the first one above.</p> </div>`; const list = el.querySelector("ul"); const empty = el.querySelector("p"); const form = el.querySelector("form"); form.querySelector("button").prepend(ctx.icon("plus")); const render = ({ notes }) => { list.hidden = !notes.length; empty.hidden = !!notes.length; list.replaceChildren(...notes.map((n) => { const li = document.createElement("li"); li.textContent = n.text; // never inject data with innerHTML return li; })); }; ctx.api("notes").then(render); const onSubmit = async (e) => { e.preventDefault(); const text = form.text.value.trim(); if (!text) return; render(await ctx.api("notes", { method: "POST", body: { text } })); form.reset(); }; form.addEventListener("submit", onSubmit); return () => form.removeEventListener("submit", onSubmit); } ``` `ctx` in page.js = `{api(path, opts), navigate(route), theme, lang, t, icon(name)}` (`lang` = the UI language, "en"/"fr"; `icon("plus")` = an `<svg>` element of the app's icon set; `navigate("/sessions?path=<topic path>&new=1&prompt=<text>")` opens a new session with the text typed in): `ctx.api` calls this extension's own API (`/api/ext/<id>/<path>`) with the session cookie and CSRF header, and returns parsed JSON. Always build the page with the **UI kit** (next section) so it looks like the rest of the app; use `textContent`, not `innerHTML`, for any data. The app only runs scripts from its own server: in page.js, no inline `<script>` added to the page and no `eval` / `new Function` - import other modules of the folder instead (`import x from './x.js'`). HTML widgets are not affected (their frame has its own policy).

## UI kit - the app's look for pages and HTML widgets Page extensions and HTML widgets get the app's design system as CSS classes (loaded for you, they follow the theme, the accent colour and the density). **Use them instead of writing your own styles**: the result looks like the app, in dark and light. Add CSS only for the layout specific to the page. ``` layout ui-page (page column, max 1152 px) · ui-section · ui-grid (responsive cards) · ui-row · ui-stack · ui-spacer text ui-h1 (page title) · ui-h2 (section/card title) · ui-h3 · ui-text · ui-muted · ui-small · ui-label · ui-num card ui-card · ui-card-header (ui-icon-box + <div><h2 class="ui-h2">…</h2><p class="ui-muted">…</p></div>) · ui-card-footer tile <button class="ui-tile"><div class="ui-icon-box">{svg}</div><div><b>Title</b><span>one line</span></div></button> icon ui-icon-box (+ ui-lg, ui-neutral) - the icon on a soft square of the accent colour button ui-btn (main action) + ui-secondary | ui-outline | ui-ghost | ui-danger, + ui-sm, ui-icon-only form <label class="ui-field"><span class="ui-label">Name</span><input class="ui-input"><span class="ui-small">hint</span></label> ui-select · ui-textarea · ui-check (checkbox) status ui-badge · ui-dot + ui-success | ui-warning | ui-error | ui-primary | ui-outline data ui-list (<ul>, rows) · ui-table (wide: inside a <div class="ui-table-wrap">) · ui-stat > ui-stat-label + ui-stat-value · ui-progress > <span style="width:40%"> other ui-steps (<ol>, li > ui-step-num + <div>) · ui-callout (+ ui-info|ui-success|ui-warning|ui-error, svg first) ui-empty (empty state: ui-icon-box ui-lg ui-neutral, ui-h2, ui-muted, a ui-btn) · ui-skeleton (loading) ui-code · ui-kbd · ui-link (button styled as a link) · ui-separator ``` Rules of the app's design to keep: one main `ui-btn` per area (others `ui-outline` / `ui-ghost`), an empty list shows `ui-empty` with one sentence and an action, data loading shows `ui-skeleton` blocks of the final size, colours only from the theme variables (`var(--primary)`, `var(--muted-foreground)`, `var(--success)`… never hex), icons not emoji. Example: `<workspace>/extensions/pages/page.js` (the "Your pages" page) and `<code dir>/examples/extensions/notes-page/`.

## HTML widget - `extensions/snake-widget/` Copy `<code dir>/examples/extensions/snake-widget/` (a working game) and adapt it. In widget.html: - `maxxing.api(path, {method, body, query})` -> Promise of the JSON returned by this extension's `handle()`; `maxxing.resize(px)`; `maxxing.theme` + `maxxing.onTheme(fn)`. - The UI kit above is already in the frame (`ui-card`, `ui-btn`, `ui-stat`…), and the theme variables too: `var(--card)`, `--foreground`, `--muted-foreground`, `--border`, `--primary`… (older names `--mx-fg`, `--mx-muted`, `--mx-border`, `--mx-accent`, `--mx-card`, `--mx-bg` still work). No icon helper in the frame: inline an `<svg>`. - The frame is sandboxed (scripts yes, same-origin no): no cookies, no localStorage, no access to the app or `/api/...` - persist through `api.py` + `ctx["state_dir"]`. Only `widget.html` is served: inline CSS/JS, or load a library from a CDN with an absolute https URL. - Keyboard games: make the canvas focusable (`tabindex="0"`) and start on click; add touch/swipe for phones.

## Overview view - `extensions/mission-control/` A view of the Overview of the Agents page (every agent at its desk), listed in its view menu after Classic and Space. `manifest.json` ```json {"id": "mission-control", "name": "Mission control", "type": "view", "icon": "radar", "version": "1.0.0", "api": 1, "agents_view": {"name": {"en": "Mission control", "fr": "Contrôle de mission"}, "icon": "radar"}} ``` (`"agents_view": true` = the extension's name and icon; a widget or a page may also declare one.) `agents-view.html` = one self-contained file in the same sandboxed frame as an HTML widget (same `maxxing.api / resize / theme / onTheme`, UI kit and theme variables, no cookies or storage), plus: - `maxxing.onData(fn)` (called at once, then at every change; also `maxxing.data`) with `{lang, new_agent_route, projects: [{name, emoji, color, agents: [Agent]}]}` - projects and agents already in the user's order, `color` = the project colour (hex). Agent = `{path, project, topic, name, display_name, description, enabled, model, status: "running"|"waiting"|"unread"|"failed"|"off"|"idle", status_text (UI language), running, waiting, unread, cost_today, last_run: {at, kind, ok, text}|null, avatar, avatar_svg, route}`. `avatar_svg` = the agent's 16x16 pixel character as SVG markup: `img.src = "data:image/svg+xml," + encodeURIComponent(a.avatar_svg)` with `image-rendering: pixelated`, sizes in multiples of 16. - `maxxing.navigate(a.route)` opens an agent; `maxxing.navigate(data.new_agent_route)` = New agent (only routes of the Agents page). - `maxxing.app("/api/agents/layout")`: read-only GET of the raw order and colors (every other path is refused); use `onData` first, it is live and has everything a view needs. Rules: render from `onData` every time (it is called again on each change, rebuild or diff, never append), use `textContent` for names and texts, show every state (`waiting` = needs the user, `unread` = new results, `failed`, `off`), make every agent clickable (also with the keyboard: a `<button>`), `maxxing.resize(document.body.scrollHeight)` after each render, light and dark (`maxxing.theme` + theme variables), a phone width (~360 px), and `@media (prefers-reduced-motion: reduce)` stops animations. Ask the user the style they want (a mission control, a farm, a train station, a plain table…) before building it. Then: **Settings -> Widgets** (or **Pages**) **-> Rescan**, Agents -> Overview -> the view menu -> its name.

## Steps 1. Ask what to show, where the data comes from, refresh rate, which secrets are needed. 2. Create the folder and files; for API calls use `urllib.request` with `timeout=10`. 3. Test the Python side directly, without the server: ```bash cd <workspace>/extensions/<id> && python3 -c " import json, api, tempfile ctx = {'id': '<id>', 'workspace': '<workspace>', 'state_dir': tempfile.mkdtemp(), 'secret': lambda n: None, 'config': {'timezone': 'UTC', 'language': 'en', 'public_url': ''}} print(json.dumps(api.card(ctx), indent=2))" # page: api.handle(ctx, 'GET', 'notes', {}, None) ``` Check `page.js` syntax with `node --check page.js` if node is available. 4. Tell the user: **Settings -> Widgets** (or **Pages**) **-> Rescan**, then check the dashboard / the new page. Errors (bad manifest, import error, exception in card) are shown on the extension's row there. 5. Record the extension's purpose and data source in the topic memory (`memory` skill).

Community library (https://harness-maxxing.com/community): extensions, widgets and skills by other people. - **Install one**: only on the user's request; clone it at the commit the listing names, read every file and tell the user what it does (network, files, keys, `api.py` = code that runs in the server with its rights) before copying it to `<workspace>/extensions/<id>/`; then Rescan. Never run its code to "try it" before that. - **Publish one the user made**: follow https://harness-maxxing.com/community/publish.md (key `HM_COMMUNITY_KEY` in the vault; never print it). Ask before creating a public repository or pushing.

The HTTP API needs a signed-in browser session, so do not try to test it with curl; use the Python test above and the UI.

Intended uses

  • Use Maxxing Extension when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.