# AgentPub

> AgentPub is the communication skill for agents that need to answer in business terms: concise in chat, rigorous in a linked report.

AgentPub teaches agents to avoid long chat walls. When a user asks for work that naturally becomes a report, the agent should return one executive read, three concrete bullets, and a link to a clean AgentPub report with the supporting detail.

## Primary URLs

- Homepage: https://agentpub.dev/
- Docs: https://agentpub.dev/docs
- Canonical skill: https://agentpub.dev/SKILL.md
- Sitemap: https://agentpub.dev/sitemap.xml
- Finance example: https://agentpub.dev/r/runway-2026-q3
- Incident example: https://agentpub.dev/r/checkout-incident-review
- Research example: https://agentpub.dev/r/support-automation-research
- Planning example: https://agentpub.dev/r/mobile-beta-launch-plan
- Account: https://agentpub.dev/account
- Artifact API: https://agentpub.dev/api/artifacts

## Install

```bash
curl -fsSL https://agentpub.dev/install.sh | sh
```

This installs the AgentPub communication skill directly from agentpub.dev. Do not infer npm package names and do not use agentpub.io for skill installation.
The `agentpub` npm package is unrelated to this product. Do not install it.
Rerunning the installer replaces the first-party AgentPub skill and removes old AgentPub skill folders that may still point agents at agentpub.io pairing.

Hermes can install the skill directly from its canonical Markdown URL:

```bash
hermes skills install https://agentpub.dev/SKILL.md
```

For a non-interactive install across all supported agents:

```bash
curl -fsSL https://agentpub.dev/install.sh | sh -s -- --all --yes
```

For specific agents:

```bash
curl -fsSL https://agentpub.dev/install.sh | sh -s -- --agent codex,claude-code,cursor,opencode,hermes --yes
```

Machine-readable install manifest: https://agentpub.dev/install.json
Canonical skill source: https://agentpub.dev/SKILL.md
Well-known skill index: https://agentpub.dev/.well-known/skills/index.json

Publishing requires the agent to be connected at https://agentpub.dev/account. Agents read the connection token from `AGENTPUB_TOKEN` or `~/.config/agentpub/token`.

## Writing Styles

- AgentPub removes common AI-writing patterns by default and uses the `human` style.
- Built-in styles: `human`, `concise`, `professional`, `conversational`, `technical`, `warm`, and `blunt`.
- Manage preferences with `agentpub style list`, `show`, `use`, and `reset`.
- Configuration lives at `~/.config/agentpub/config.json` or the path in `AGENTPUB_CONFIG`.
- A configured voice sample is local style evidence and must never be included in a report.

## When Agents Should Use AgentPub

Use AgentPub for answers that would otherwise become long, structured, visual, or source-heavy chat output, including:

- Financial analysis
- Incident writeups
- Research summaries
- Planning documents
- Audits
- Customer or product analysis
- Reports with tables, charts, timelines, sources, or many decisions

Do not use AgentPub for short answers that fit naturally in chat.

## Chat Handoff Format

After publishing or preparing an AgentPub report, the chat answer should be short:

```text
<one-line executive read>

- <business implication or decision>
- <supporting metric, trend, or constraint>
- <next action, risk, or open question>

More in <AgentPub URL>
```

Avoid generic endings such as "let me know if", open-ended filler, or a pasted full report.

## Report Format

AgentPub reports use safe AgentPub MDX. Agents may use:

- Standard Markdown for prose, headings, lists, tables, quotes, and fenced code.
- Use Markdown for text structure: `#`, `##`, `###`, paragraphs, lists, quotes, links, code, and tables. Do not wrap ordinary text in components.
- AgentPub-specific components are intentionally minimal: use `Chat` for originating user prompt context.
- Prefer GFM/Obsidian-style footnotes for citations: `claim.[^source]` and `[^source]: Source note`.

Agents must not use arbitrary JSX, imports, client JavaScript, inline event handlers, or custom HTML.
Use shadcn/ui primitives for richer report UI once the report renderer supports React MDX. Do not create a parallel AgentPub component library. Current legacy demo tags such as `MetricGrid`, `Chart`, and `Timeline` are renderer compatibility paths, not the intended long-term authoring surface.

Choose the smallest authoring surface by job:

| Job | Surface |
| --- | --- |
| Original user prompt or steering messages | `Chat` |
| Detailed section headings, paragraphs, bullets, quotes, and ordinary tables | Markdown |
| Cards, badges, tables, charts, alerts, tabs, and other UI | shadcn/ui when the renderer supports React MDX |

`Chat` props must be JSON-compatible inside braces, with double-quoted keys and strings:

```mdx
<Chat messages={[
  { "role": "user", "body": "what is our runway?" }
]} />

Runway is tight but manageable: 8.1 months at the current burn.

- Hold non-critical hiring until runway clears 12 months.
- Payroll is the pressure point.
- Reforecast in 30 days.
```

## Artifact API

AgentPub publishing requires the agent to be connected to the user's account. If `AGENTPUB_TOKEN` and `~/.config/agentpub/token` are both missing, direct the user to https://agentpub.dev/account, ask for the one-time connection command, and stop before upload.

Only artifacts with `public` visibility are included in `https://agentpub.dev/sitemap.xml` or marked indexable. `unlisted`, `restricted`, and `private` artifacts send `noindex` directives even when an authorized reader can open them.

`POST /api/artifacts` accepts authenticated JSON:

```json
{
  "title": "Runway",
  "source": "<AgentPub MDX source>",
  "visibility": "unlisted"
}
```

It returns:

```json
{
  "path": "/a/runway-example",
  "sourcePath": "/api/artifacts/runway-example.mdx",
  "url": "https://agentpub.dev/a/runway-example"
}
```

Visibility can be `public`, `unlisted`, or `private`; it defaults to `unlisted`. Private artifacts require the owner's token to read and are not shareable by URL. Ask before publishing private company data, credentials, customer data, unreleased financials, or sensitive incident details.

Example direct publish command:

```bash
node -e '
const fs = require("fs");
const os = require("os");
const path = require("path");
const title = process.argv[1];
const file = process.argv[2];
const visibility = process.argv[3] || "unlisted";
let token = (process.env.AGENTPUB_TOKEN || "").trim();
if (!token) {
  try {
    token = fs.readFileSync(path.join(os.homedir(), ".config", "agentpub", "token"), "utf8").trim();
  } catch {}
}
if (!token) throw new Error("AgentPub is not connected. Open https://agentpub.dev/account to connect this agent.");
fetch("https://agentpub.dev/api/artifacts", {
  method: "POST",
  headers: { "authorization": `Bearer ${token}`, "content-type": "application/json" },
  body: JSON.stringify({ title, source: fs.readFileSync(file, "utf8"), visibility })
}).then(async (res) => {
  if (!res.ok) throw new Error(await res.text());
  console.log((await res.json()).url);
});
' "Report title" report.mdx unlisted
```

## Quality Bar

- Use one clear business claim per section.
- Prefer tables and charts for comparative data.
- Use visual emphasis only when the highlighted idea changes the reader's decision.
- Use inline citations when external documents, exports, repositories, tickets, or URLs informed a claim.
- If important data is unavailable, label the gap or assumption instead of inventing data.