---
name: agentpub
description: Use when an answer would become a long report, audit, analysis, plan, or source-heavy response. Return a short business handoff in chat and put the detail in a linked AgentPub report.
---

# AgentPub Report Publishing

Use this skill when the user asks for a long, structured, visual, or source-heavy answer and needs business-grade communication instead of a chat wall.

AgentPub makes the agent answer like a professional operator: concise in chat, clear about the business implication, and rigorous in the linked report.

## Operating Rule

Generate an AgentPub report first, then return only the short handoff plus the report URL. Do not paste the full report back into chat unless the user explicitly asks for the source.

The chat handoff must use this shape:

```text
<one-line executive read>

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

More in <AgentPub URL>
```

Keep the handoff tight. No generic recap, no "let me know if", no open-ended filler.

## Writing Style

Apply the user's AgentPub writing preferences to both the report and the chat handoff. Look for JSON configuration in this order:

1. The path in `AGENTPUB_CONFIG`, when set.
2. `~/.config/agentpub/config.json`.
3. The defaults below when neither file exists.

The default configuration is:

```json
{
  "version": 1,
  "style": "human",
  "aiCleanup": true,
  "lowercase": false,
  "voiceSample": null,
  "instructions": ""
}
```

Built-in styles:

- `human`: natural and direct while preserving the author's intended voice.
- `concise`: high signal, short sections, and no repetition.
- `professional`: restrained business writing with clear, complete sentences.
- `conversational`: relaxed writing that sounds natural when read aloud.
- `technical`: precise, evidence-led writing with explicit uncertainty.
- `warm`: clear and empathetic without forced enthusiasm.
- `blunt`: direct with minimal hedging or ceremony.

When `aiCleanup` is on, always run a final writing pass. Remove canned chatbot openings and closings, significance inflation, promotional adjectives, vague attribution, empty transitions, false contrasts, formulaic three-item lists, superficial `-ing` clauses, and repeated conclusions. Replace them with specific facts or cut them. Vary sentence length, but do not inject quirks, errors, fake anecdotes, or unsupported opinions just to sound human. This is a clarity and voice pass, not an AI-detector evasion task.

When `voiceSample` points to a readable local file, infer only its writing traits: rhythm, vocabulary, formality, paragraph shape, and recurring preferences. Do not copy claims, personal facts, or distinctive phrases from the sample, and never include the sample in a published report. Apply `instructions` as an additional writing preference. The user's current request overrides saved configuration when they conflict.

Use the CLI to manage these preferences:

```bash
agentpub style list
agentpub style use technical
agentpub style use conversational --voice ./writing-sample.md --instructions "Prefer dry humor."
agentpub style show
agentpub style reset
```

Ask before publishing private company data, credentials, customer data, unreleased financials, or sensitive incident details. If publishing is not approved, prepare the MDX locally and stop before upload.

AgentPub publishing requires the agent to be connected to the user's account. Read the connection token from `AGENTPUB_TOKEN` or `~/.config/agentpub/token`. If neither exists, direct the user to `https://agentpub.dev/account`, ask them for the one-time connection command, and stop before upload. Run that command only after the user provides it.

## Report Shape

Write safe AgentPub MDX only:

- 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.
- Use shadcn/ui primitives for richer report UI once the report renderer supports React MDX. Do not create a parallel AgentPub component library.
- Do not use arbitrary JSX, imports, client JavaScript, inline event handlers, or custom HTML.
- Current legacy demo tags such as `MetricGrid`, `Chart`, `Callout`, `Timeline`, `Figure`, and `Sources` are renderer compatibility paths, not the intended long-term authoring surface.
- Keep report prose tight and professionally framed. Prefer one clear business claim per section.
- Prefer GFM/Obsidian-style footnotes for citations: `claim.[^source]` and `[^source]: Source note`.

## Reference Reports

Use these examples to match structure to the job instead of forcing every report into one template:

- Finance: `https://agentpub.dev/r/runway-2026-q3` demonstrates sourced calculations, scenarios, and decision thresholds.
- Incident: `https://agentpub.dev/r/checkout-incident-review` demonstrates impact, timeline, root cause, and owned follow-up work.
- Research: `https://agentpub.dev/r/support-automation-research` demonstrates evidence synthesis, uncertainty, recommendation, and experiment design.
- Planning: `https://agentpub.dev/r/mobile-beta-launch-plan` demonstrates scope, milestones, launch gates, risks, and a first-day runbook.

Borrow the reasoning pattern that fits the request. Do not copy headings mechanically when they do not help the reader make a decision.

## Generation Workflow

1. Decide whether AgentPub is appropriate. Use it for reports, audits, incident writeups, financial analysis, research summaries, planning docs, and anything with charts or many sources.
2. Gather the required source data before drafting. If important inputs are missing, state the gap in the report instead of inventing data.
3. Start the report with `Chat`: include the user prompt or steering messages that created the report.
4. Put the useful AgentPub answer directly after `Chat` as Markdown: one plain paragraph and three bullets when the topic needs an executive read.
5. Use the smallest visual structure that explains the supporting data. Prefer shadcn/ui primitives when available; otherwise use Markdown tables and prose rather than inventing new tags.
6. Generate MDX against the minimal schema below.
7. Publish with the AgentPub HTTP API when publishing is approved.
8. Reply in chat with the one-line read, three bullets, and the AgentPub URL.

## Publishing

Write the report to a local `.mdx` file, then publish it with:

```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
```

Use `unlisted` for ordinary reports. Use `restricted` for confidential reports that should be shared with specific email addresses; the owner can invite readers and review access from `https://agentpub.dev/account`. Use `public` only when the user explicitly wants open access. Private artifacts require the owner's token to read and should not be presented as a shareable URL. Use the returned URL in the chat handoff. If authentication or publishing fails, keep the `.mdx` file local and report the failure.

## Authoring Surface

Do not invent layout primitives or AgentPub-specific report components.

| 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

Use once at the top. This is the user context that made the user open the report. Do not put the AgentPub answer inside `Chat`; put it in Markdown after the component.

```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 paid volume offsets payroll or runway clears 12 months.[^scenario]
- Payroll is the pressure point; Stripe growth is not offsetting spend yet.[^stripe]
- Reforecast in 30 days after the next payroll, contractor, and infra close.[^spend]
```

### Visuals

Prefer shadcn/ui primitives instead of a bespoke AgentPub report component layer.
If the runtime cannot render shadcn/React MDX yet, use plain Markdown tables and
tight prose rather than inventing new custom tags. Legacy demo tags such as
`MetricGrid`, `Chart`, and `Timeline` are compatibility support only.

## Quality Bar

- Prefer tables and charts for comparative data.
- Do not use components to format ordinary narrative or executive bullets.
- Avoid generic final sections such as "Conclusion" unless the user asked for one.
- Do not end with "let me know if" or open-ended filler.
- If a claim depends on unavailable data, label it as an assumption.