---
activeChapter: "03"
rootPath: "../"
learnPath: "index.html"
visionPath: "../vision/index.html"
permalink: "learn/03-build-your-first-agent.html"
---
{% extends "base.njk" %}
{% block title %}Build your first agent — Learn Houston{% endblock %}
{% block meta %}
<meta name="description" content="Create a Houston agent in 10 minutes. Write a manifest, add your prompts, import it, and test.">
{% endblock %}
{% block stylesheets %}
<link rel="stylesheet" href="style.css?v=3">
{% endblock %}
{% block body %}
    {% include "nav-docs.njk" %}

    <div class="layout">
      {% include "sidebar-learn.njk" %}

      <main class="content">
        <div class="content-label">Chapter 03</div>
        <h1>Build your first agent.</h1>
        <p class="lead">
          A Houston agent is a JSON file and a prompt. You can build one
          in 10 minutes.
        </p>

        <div class="toc">
          <div class="toc-label">On this page</div>
          <ol>
            <li><a href="#what-you-need">What you need</a></li>
            <li><a href="#the-manifest">The manifest</a></li>
            <li><a href="#the-prompt">The prompt</a></li>
            <li><a href="#import-and-test">Import and test</a></li>
            <li><a href="#publish">Publish to GitHub</a></li>
            <li><a href="#advanced">Going further</a></li>
          </ol>
        </div>

        <h2 id="what-you-need">What you need</h2>
        <p>
          Two files. That's it.
        </p>
        <ul>
          <li><code>houston.json</code> — defines what your agent looks
          like, its name, icon, and category.</li>
          <li><code>CLAUDE.md</code> — the instructions your agent follows.
          This is the brain.</li>
        </ul>
        <p>
          Optional: an <code>icon.png</code> (256x256) for the store card.
          Without one, Houston uses the Lucide icon from your manifest.
        </p>

        <h2 id="the-manifest">The manifest</h2>
        <p>
          Here's a minimal <code>houston.json</code> for a bookkeeping agent:
        </p>
        <pre><code>{
  "id": "bookkeeper",
  "name": "Bookkeeper",
  "description": "Categorize expenses, reconcile accounts, prepare reports.",
  "icon": "Calculator",
  "category": "business",
  "author": "Your Name",
  "tags": ["accounting", "bookkeeping", "finance"]
}</code></pre>
        <p>
          The <code>id</code> must be unique. Use kebab-case. This is how
          Houston identifies your agent across installs and updates.
        </p>

        <h3>Fields reference</h3>
        <table class="fields-table">
          <thead><tr><th>Field</th><th>Required</th><th>What it does</th></tr></thead>
          <tbody>
            <tr><td><code>id</code></td><td>Yes</td><td>Unique identifier (kebab-case)</td></tr>
            <tr><td><code>name</code></td><td>Yes</td><td>Display name in the store and sidebar</td></tr>
            <tr><td><code>description</code></td><td>Yes</td><td>One-line description for the store card</td></tr>
            <tr><td><code>icon</code></td><td>No</td><td>Lucide icon name (fallback if no icon.png)</td></tr>
            <tr><td><code>category</code></td><td>No</td><td>productivity, development, research, creative, or business</td></tr>
            <tr><td><code>integrations</code></td><td>No</td><td>Composio toolkit slugs your agent uses (e.g. <code>["gmail", "googlecalendar"]</code>)</td></tr>
            <tr><td><code>claudeMd</code></td><td>No</td><td>Inline CLAUDE.md content (alternative to a separate file)</td></tr>
            <tr><td><code>agentSeeds</code></td><td>No</td><td>Files to create in every new agent instance</td></tr>
            <tr><td><code>agents</code></td><td>No</td><td>Multiple prompt profiles for multi-agent setups</td></tr>
          </tbody>
        </table>

        <h2 id="the-prompt">The prompt</h2>
        <p>
          Create a <code>CLAUDE.md</code> file next to your manifest. This
          is where your domain expertise lives.
        </p>
        <pre><code># Bookkeeper

You are a bookkeeping agent. You help users manage their
finances by categorizing expenses, reconciling accounts,
and preparing reports.

## What you do
- Categorize transactions from bank statements
- Flag unusual expenses for review
- Generate monthly summaries
- Answer questions about spending patterns

## Rules
- Always ask which time period the user wants before starting
- Round currency to two decimal places
- When in doubt about a category, ask the user
- Never fabricate transaction data</code></pre>
        <p>
          The quality of your agent is the quality of this prompt. This is
          where founders spend their time. The domain knowledge, the edge
          case handling, the workflow design. This is your product.
        </p>

        <h2 id="import-and-test">Import and test</h2>
        <p>
          Two ways to get your agent into Houston:
        </p>
        <h3>From GitHub (recommended)</h3>
        <ol>
          <li>Push your <code>houston.json</code>, <code>CLAUDE.md</code>,
          and optional <code>icon.png</code> to a GitHub repo.</li>
          <li>In Houston, click <strong>New Agent</strong>.</li>
          <li>Switch to the <strong>GitHub</strong> tab.</li>
          <li>Paste your repo URL or <code>owner/repo</code>.</li>
          <li>Houston downloads the files and installs the agent.</li>
        </ol>
        <h3>Manually</h3>
        <ol>
          <li>Create a folder at <code>~/.houston/agents/your-agent-id/</code></li>
          <li>Put your <code>houston.json</code> and <code>CLAUDE.md</code> there.</li>
          <li>Restart Houston. Your agent appears in the New Agent picker.</li>
        </ol>
        <p>
          Once installed, create a new agent from your definition. Houston
          seeds the working directory with your CLAUDE.md and any files
          from <code>agentSeeds</code>. Start chatting. Iterate on the
          prompt until it feels right.
        </p>

        <h2 id="publish">Publish to GitHub</h2>
        <p>
          Your GitHub repo is your distribution channel. The minimum
          repo structure:
        </p>
        <pre><code>your-agent/
├── houston.json
├── CLAUDE.md
└── icon.png        (optional, 256x256)</code></pre>
        <p>
          Anyone can import your agent by pasting the repo URL into Houston.
          When you push updates, Houston detects them and updates
          installed agents automatically.
        </p>

        <h2 id="advanced">Going further</h2>
        <h3>Seeding files</h3>
        <p>
          Use <code>agentSeeds</code> to pre-populate every new agent
          instance with default files:
        </p>
        <pre><code>"agentSeeds": {
  ".houston/prompts/execution.md": "You are a coding agent...",
  ".houston/config.json": "{\"mode\": \"default\"}"
}</code></pre>

        <h3>Multi-agent setups</h3>
        <p>
          One agent definition can have multiple prompt profiles. Each
          profile gets its own prompt file and create button:
        </p>
        <pre><code>"agents": [
  {
    "id": "execution",
    "name": "Coder",
    "promptFile": "execution.md",
    "createLabel": "New Mission"
  },
  {
    "id": "planning",
    "name": "Planner",
    "promptFile": "planning.md",
    "createLabel": "New Planning Session"
  }
]</code></pre>

        <div class="pager">
          <a href="02-symmetric-participation.html">
            <div class="pager-label">← Previous</div>
            <div class="pager-title">Humans and AI, as equals</div>
          </a>
          <a href="04-custom-components.html" class="next">
            <div class="pager-label">Next →</div>
            <div class="pager-title">The agent shell</div>
          </a>
        </div>
      </main>
    </div>
  {% endblock %}