You've built an agent that does something useful. Now you want others to be able to deploy it without starting from scratch. That's what templates are for.

A template is three things: a public Git repo, a manifest.json at the root, and a workspace/ directory.

On deploy, the platform clones the repo, runs scripts.build to install dependencies, starts any server with scripts.start under pm2, registers routes and cron tasks, and injects secrets as environment variables. The agent then reads workspace/AGENTS.md at the start of every session.

The workspace files aren't config. They're markdown the LLM reads.

SOUL.md shapes how the agent makes decisions. BOOTSTRAP.md is the script for the first conversation. HEARTBEAT.md tells the agent what to do on each scheduled tick. Write them like instructions for a person, because that's what they are.

The first five minutes someone spends with a deployed template is the experience you designed.

The manifest.json drives all of it:

{
  "$schema": "https://agents.pinata.cloud/schemas/manifest.v1.json",
  "version": 1,

  "agent": {
    "name": "Your Agent",
    "description": "One sentence. Sells the use case.",
    "vibe": "sharp, confirms before acting",
    "emoji": "🤖"
  },

  "template": {
    "slug": "your-agent",
    "category": "general",
    "tags": ["your", "tags"],
    "partnerName": "You"
  },

  "secrets": [
    {
      "name": "API_KEY",
      "description": "Your API key",
      "guideUrl": "https://example.com/api-keys",
      "guideSteps": ["Go to the dashboard", "Click API Keys", "Copy the key"],
      "required": true
    }
  ],

  "scripts": {
    "build": "cd workspace/projects/app && npm install --include=dev",
    "start": "cd workspace/projects/app && npx vite --host 0.0.0.0 --port 5173"
  },

  "routes": [
    { "port": 5173, "path": "/app", "protected": false }
  ],

  "tasks": [
    {
      "name": "daily-check",
      "prompt": "Run your daily check-in routine.",
      "schedule": "0 9 * * *",
      "enabled": true
    }
  ],

  "skills": [
    { "cid": "bafybeicglyjdb6wrrcbfyu6i2fe4lpxdxgvfvlht7yzdim7cvwt656whue", "name": "@pinata/platform" }
  ]
}

The skills[] entry bundles the @pinata/platform skill at deploy time, giving the agent a CLI to manage its own routes, secrets, and tasks from inside the container. The base useful-assistant template includes it, and so should almost anything you build. The full field reference lives in the _docs block inside that manifest; pull it up on GitHub when you need it.

Building on Pinata first, then exporting, is the faster path for most agents.

Start with an existing agent on agents.pinata.cloud. Let it run. Chat with it. Tune the workspace files through actual use. When it behaves the way you want, clone the repo, add a manifest.json, and submit.

Pinata agents are Git repos. Push and pull work natively:

git clone https://agents.pinata.cloud/git/<your-agent-id> my-template
# add manifest.json, clean up personal files, push to GitHub
node cli.mjs submit-template https://github.com/you/my-template

The main advantage is feedback. A SOUL.md written after two weeks of real conversations is more specific than anything you'd produce cold. The agent reveals, through actual behavior, which situations needed rules. You can't replicate that at a desk.

If you're building for the Hermes engine (Nous Research's runtime, which ships with persistent memory, session search, and the platform skill loaded by default), this path gives you something local development can't: workspace files that evolved against the actual runtime. Hermes behaves differently from OpenClaw, and a template built on a live Hermes agent captures that difference.

Before submitting, clean out your personal context. Reset IDENTITY.md and USER.md to blank placeholders, delete the memory/ directory, remove any log files. Whoever deploys your template starts fresh.

This path suits conversational agents, personal assistant variants, and anything whose behavior only makes sense after you've lived with it.

The other path is to clone the template repo and build locally.

Clone PinataCloud/agent-templates, copy an existing template as your starting point, and build in your own editor:

git clone https://github.com/PinataCloud/agent-templates
cp -r openclaw/basic/useful-assistant openclaw/my-template

Edit the manifest, write the workspace files, add your app code, push to a public GitHub repo, and submit:

node cli.mjs submit-template https://github.com/you/repo \
  --ref=refs/heads/main \
  --path=openclaw/my-template   # for monorepos

You get git history from day one and your own tooling. LLM assistance works well for the scaffolding. Paste in the manifest schema and the workspace file conventions and have it generate the initial files. The _docs block in the base manifest gives it everything it needs.

For templates that ship a web app, this path is cleaner. The web-master template ships a full Astro SSR site, every component, the build pipeline, the port route, all written locally before it was ever deployed. The MoonPay partner templates work the same way: a CLI pre-installed in setup.sh, its commands documented in SOUL.md, the whole thing managed through structured commits.

Workspace files written before you've run the agent stay generic. Plan for a round of tuning after the first deploy. Treat the initial workspace files as a draft and sharpen them against real behavior.

This path suits web app templates, partner templates built around a specific CLI, and anything where structured version control matters from the start.

Most good templates use both. Build the manifest, setup.sh, and any app code locally. Deploy early, even with placeholder workspace files. Use the live agent to develop SOUL.md, BOOTSTRAP.md, and HEARTBEAT.md. Export and clean up when the behavior is right.

The workspace files are where the template's quality shows.

SOUL.md is behavioral programming. The versions that work are decision rules for situations the agent will actually face. Here's a line from agent-with-mpp-wallet:

When an API returns a 402, the response may include multiple payment methods. Always use the Tempo payment method exclusively. Ignore any non-Tempo options entirely. Do not read their pricing, do not attempt to pay via them.

That's a rule the agent applies every time. "Be cost-conscious" is a character trait the model interprets however it feels in the moment. Write SOUL.md like a contractor brief. Cover the decisions that matter. Every situation you leave blank is one the agent improvises.

BOOTSTRAP.md runs exactly once, on the first conversation. A good one has a concrete opening line, ordered steps with actual commands, edge cases handled, and one instruction at the end: delete this file. From web-master:

"Hey! I'm Web Master. There's already a site running at [your site URL]. Tell me a bit about yourself and what you want to build."

The file then walks through what to learn, in what order, and what to do with each answer. A BOOTSTRAP with real steps produces an agent that feels like a product from the first message.

HEARTBEAT.md is what makes an agent feel alive between conversations. When it carries literal commands and a clear expected output, the agent runs them on every tick. Here's how moonpay-prediction-trader does it:

Run a full book review:
  mp prediction-market position list --provider polymarket --wallet <address>
  mp prediction-market pnl retrieve --provider polymarket --wallet <address>

Report: movers above 10%, resolved markets, USDC balance, top 3 trending markets with a one-line thesis.
Update book.md with current prices.

If your template has scheduled tasks in manifest.json, write the heartbeat prompt the same way: exact commands, expected output format, what to do with results.

AGENTS.md loads every session. It's the agent's standing procedure for how to use memory, what it can do without asking, and what requires confirmation. The base template's version handles this well. Keep it unless your agent has unusual session conventions.

IDENTITY.md and USER.md ship blank. The deploying user fills them in during the BOOTSTRAP conversation. Both files are theirs to own from deploy day.

Six things separate good templates from the rest.

agent.vibe is a system-prompt fragment, not a tagline. "Analytical, contrarian, risk-aware, never bets without showing the thesis" is a behavioral constraint the agent applies. "Thoughtful" is decoration.

SOUL.md covers your agent's specific decisions. Generic principles are already in the model. The rules it actually needs are the ones you know and it doesn't: the domain-specific edge cases, the guardrails that matter for what this agent does.

BOOTSTRAP.md has a concrete opening line and real commands. Every branch handled. Every edge case documented. Ends with: delete this file.

HEARTBEAT.md has the actual shell commands, the expected output format, and what to do with results. Write it like a recurring brief to a contractor.

Secrets have a guide. guideUrl and guideSteps[] on every secret means a deploying user can get from zero to configured without leaving the deploy flow. Mark secrets required: false when the agent works without them. Every optional secret you mark required is a barrier you're choosing to add.

Web app templates work on first deploy. scripts.build handles everything without manual steps. scripts.start binds to 0.0.0.0. Routes are pre-configured in manifest.json. BOOTSTRAP.md tells the agent how to find and verify its own URL. The whole thing runs the moment someone clicks deploy.

Go through this before you submit:

• slug is lowercase, hyphens only
• description is one sentence that says what the agent does
• README.md has example prompts or use cases and any post-deploy steps
• Every required secret has guideUrl + guideSteps
• workspace/IDENTITY.md and workspace/USER.md are blank
• workspace/BOOTSTRAP.md has a specific onboarding flow for this template
• workspace/SOUL.md has operational rules, not generic values
• scripts.build is self-contained, no steps left to the README
• You deployed this template yourself and the first conversation worked

Then:

node cli.mjs submit-template https://github.com/you/your-template \
  --ref=refs/heads/main

# monorepo:
node cli.mjs submit-template https://github.com/you/monorepo \
  --ref=refs/heads/main \
  --path=openclaw/your-template

The template lands in pending_review. After Pinata reviews it, it publishes. Re-submitting increments the version.

The CLI flow above is the partner path. Marketplace publication is currently gated to ecosystem partners; [email protected] is the route in. The open path is a PR against PinataCloud/agent-templates, which lands your template in the repo as a working example others can clone and deploy.

A few ideas worth building. A monitoring agent that watches a URL or GitHub repo and fires a Telegram alert on failure. A developer assistant pre-loaded with the GitHub skill and your team's code review conventions in SOUL.md. A content pipeline that pulls from an RSS feed and posts summaries on a schedule. And if you're already running on Hermes, you're well-positioned to publish the first template for that runtime.

A template with a working BOOTSTRAP, a SOUL.md grounded in real decisions, and a heartbeat that does something useful is already in the top tier of what's published.