> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SEO helper: an agent that drafts your blog posts

> Copy a shared template, connect GitHub, attach your site prompt, and get a researched blog post as a draft pull request on a schedule you set.

By the end of this workbook you will have an agent that researches a keyword, writes a blog post in your voice, draws its own figures, opens a **draft pull request** on your repository, and emails you the link. It runs on a schedule you choose, and it never merges anything.

It takes about twenty minutes, most of which is writing the description of your own site.

<Note>
  This template packages the [SEO Agent Pack](https://github.com/DigiHold/seo-agent-pack) by Nicolas Lecocq, MIT licensed. The method is his. This workbook covers running it on Orca.
</Note>

## Before you start

<CardGroup cols={2}>
  <Card title="A GitHub repository" icon="github">
    The repo your blog lives in, on an account you can authorize. Required. Without it the agent has nowhere to deliver and will stop rather than write something it cannot hand over.
  </Card>

  <Card title="A DataForSEO account" icon="chart-simple">
    Where the real keyword data comes from: search volume, difficulty and cost per click. Pay as you go, and a small deposit lasts months. Set it up before you start, because the agent will not run without it.
  </Card>
</CardGroup>

You do not need to install anything, and nothing runs on your own machine.

***

## Step 1: Open the template and copy it

<Steps>
  <Step title="Open the share link">
    Open [the SEO helper template](https://app.orcapods.ai/templates?org=orca-1785436513544054466\&template=seo-helper).

    You do not need an account to look. The page shows the full description and, further down, a **What gets copied** panel listing everything the template installs: one scheduled run, two agents, one pod, and one skill.
  </Step>

  <Step title="Press Copy template">
    If you are not signed in yet, Orca sends you to sign up or sign in first, and creates your workspace if this is your first visit. When that is done it brings you straight back to this same template page rather than dropping you on a dashboard.

    **Press Copy template again once you are back.** The first press only started the detour.
  </Step>

  <Step title="Review the copy plan">
    A plan appears listing every asset, its kind, and the name it will take in your workspace.

    On a new workspace nothing clashes and you can install as is. If a name is already in use, that row is flagged **name taken** and Orca proposes a free one ending in `-copy`. You can type your own name instead, or untick the row to skip it. Nothing you already own is ever overwritten.
  </Step>

  <Step title="Install">
    Press **Copy selected assets**.

    Open **Agents** and you will see `seo-writer` and `seo-media`. Open **Skills** and you will see `seo-engine`. They are yours now, and every one of them is editable.
  </Step>
</Steps>

## Step 2: Connect GitHub

The agent needs two connections before it will run: GitHub, so it has somewhere to deliver, and DataForSEO, so it picks keywords from real data. Start with GitHub.

<Steps>
  <Step title="Open the writer agent">
    Go to **Agents** and click `seo-writer`. It opens as a panel showing its capabilities, its skill, and its connected apps.

    Fresh from a copy it reads **Needs setup**, with a banner headed **Finish setting up this agent**. The banner is honest about the consequence: runs are refused until the required items are resolved, and nothing is charged for a refused run.
  </Step>

  <Step title="Press Connect on the GitHub row">
    The banner names each unresolved dependency and puts a **Connect** button beside it. That takes you to Connected apps with the right app already in focus.
  </Step>

  <Step title="Authorize the account that owns your blog repo">
    A GitHub consent screen opens. Authorize the account or organization that owns the repository you want posts delivered into.
  </Step>

  <Step title="Check it went active">
    Back in Orca the connection should read **ACTIVE**. If it reads `INITIATED` the popup did not finish; if it reads `FAILED` or `EXPIRED`, disconnect and try again.

    The agent's **Dependencies** tab is the place to confirm. It lists everything the agent leans on outside its own prompt, healthy rows included, with a status against each.
  </Step>
</Steps>

<Warning>
  The agent never goes looking for a repository. It only writes to the exact `owner/name` you give it in Step 4. Connecting GitHub grants access; naming the repo is what points the run at a target.
</Warning>

## Step 3: Connect DataForSEO

This is where the keyword numbers come from. The agent is not allowed to invent search volumes, so without this connection it has nothing to choose a topic with, and the run is refused before it starts.

<Steps>
  <Step title="Create a DataForSEO account">
    Sign up at [dataforseo.com](https://dataforseo.com) and top up a small amount. It is pay as you go and keyword lookups cost a fraction of a cent, so a few pounds goes a long way.
  </Step>

  <Step title="Connect it in Orca">
    Back on `seo-writer`, press **Connect** on the DataForSEO row of the setup banner, and enter the credentials from your DataForSEO dashboard.
  </Step>

  <Step title="Confirm the agent is ready">
    With both connections active, the agent's status changes from **Needs setup** to **Ready** and the setup banner disappears.
  </Step>
</Steps>

## Step 4: Write your site prompt

This is the step that decides whether the drafts are any good, so it is worth ten unhurried minutes.

The agent starts every run knowing nothing about you. That is deliberate: it is what lets the same pair of agents write for several different sites without the facts bleeding together. Everything it needs comes from a **prompt** you write once and attach to the run.

<Steps>
  <Step title="Open Prompts">
    Go to **Prompts** and create a new one. Name it after your site, for example `example-com-site-prompt`.
  </Step>

  <Step title="Fill in the three facts that only you know">
    Your domain, your repository as `owner/name`, and three to five subjects you want to be known for. Everything else has a sensible default or can be discovered inside your repo.

    If your blog is plain Markdown files in one folder, this is genuinely short:

    ```text theme={null}
    Write and deliver one SEO post, following your seo-engine skill and its
    run protocol. Pick the keyword yourself from the lanes below unless I
    name a topic.

    ## Domain and repo
    Domain: example.com. Repo: acme/website, base branch main.
    Posts live at src/content/blog/, format md.
    Sitemap: https://example.com/sitemap.xml

    ## What we sell, and who reads this
    We sell invoicing software to freelance designers.
    Readers are self-employed designers who bill by project.

    ## Allowed lanes
    1. Getting paid on time: chasing, deposits, late fees
    2. Pricing creative work
    3. Bookkeeping for one-person studios

    ## Forbidden lanes
    Generic business advice, crypto, AI news.

    ## Voice
    Practical and direct, first person plural, no hype. Contractions always.

    ## Delivery
    Branch seo/<slug>, PR titled [SEO draft] <title>, label seo-draft, base main.
    Draft PRs only. A human merges. Never push to main.
    ```
  </Step>

  <Step title="Add anything a glance at the folder would not reveal">
    If a post has to carry front-matter fields, update an index or registry file, put images in a particular place, or pass a build check, say so. Copy the field names from a real post. This is the difference between a draft you merge and a draft you rewrite.
  </Step>

  <Step title="Save it">
    You attach it to the scheduled run in the next step, and you can edit it any time afterwards. Edits are picked up on the very next run, with nothing to redeploy.
  </Step>
</Steps>

<Note>
  Orca calls these **Prompts** in the dashboard and **[contexts](/concepts/contexts)** in the concept docs. They are the same object.
</Note>

## Step 5: Set up the scheduled run

The template brought a scheduled run with it, and it arrives **stopped** so that nothing happens until you are ready.

<Steps>
  <Step title="Open Scheduled Runs">
    In the sidebar, under **Automation**, open **Scheduled Runs** and click the run that came with the template.
  </Step>

  <Step title="Attach your site prompt">
    On the **Context** tab, attach the prompt you wrote in Step 4. Without it the run stops at pre-flight and tells you exactly what was missing, rather than guessing at a repository.
  </Step>

  <Step title="Set a time you will actually read drafts">
    On the **Schedule** tab, pick the time of day and your timezone. Something early enough that the pull request is waiting when you start work.
  </Step>

  <Step title="Check the dependencies">
    The **Dependencies** tab lists everything this run leans on outside its prompt: its skill, its capabilities, and its connected apps. GitHub should be there and healthy before you go further.
  </Step>
</Steps>

Leave it stopped for now. Test first.

## Step 6: Test it with Run now

<Steps>
  <Step title="Press Run now">
    **Run now** starts one run immediately and does not touch the schedule.
  </Step>

  <Step title="Watch it work">
    Open the run to follow it live. A full run takes a few minutes: it picks a keyword, reads the current top results, drafts the post, briefs the media agent for figures, then opens the pull request.
  </Step>
</Steps>

## Step 7: Check your email and the pull request

<Steps>
  <Step title="Open the email">
    A healthy run emails you a link to the pull request it opened.
  </Step>

  <Step title="Read the pull request">
    On GitHub you should find a **draft** pull request labelled `seo-draft` on a branch named `seo/<slug>`, carrying the post, its images, and any index or sitemap updates in the same branch.
  </Step>

  <Step title="Decide">
    Read it. Merge it if you are happy, and merging is what publishes it. Nothing reaches your site until you do.
  </Step>
</Steps>

## Step 8: Start the schedule

Once a test run has produced a pull request you are happy to have received, go back to the scheduled run and press **Start**. From then on it runs at the time you chose.

***

## When something goes wrong

A blocked run does not guess. It stops, records exactly what was missing, and opens nothing.

| What you see                                                | What it means                                                               | What to do                                                                                |
| ----------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| The agent reads **Needs setup** and runs are refused        | A required dependency is unresolved                                         | Open the agent and use the **Connect** button on the banner row that names it             |
| Run stops immediately, mentions missing site facts          | No prompt was attached, or it is missing the domain, the repo, or the lanes | Attach your site prompt on the run's **Context** tab, and check all three facts are in it |
| Pull request opened on the wrong repository                 | The prompt names a different `owner/name`                                   | Fix the repo line in your prompt. The agent only ever writes to the repo you name         |
| Runs are refused and the banner names `composio-dataforseo` | DataForSEO is not connected, or its credentials lapsed                      | Connect it from the banner row. Check your DataForSEO balance has not run out             |
| No email arrived, but a pull request exists                 | Delivery succeeded, the notification did not                                | Check the run's own output for the link                                                   |
| The draft reads poorly                                      | Usually the prompt rather than the agent                                    | Tighten the voice and style rules in your site prompt, then run again                     |

**Still stuck?** Email [support@okik.io](mailto:support@okik.io) with the name of the scheduled run and roughly when it ran, and we will look at it.

## Making it better week by week

The first few drafts will need work, and that is normal rather than a sign the setup is broken.

When a draft disappoints you, do not stop at fixing the draft. Edit the pull request by hand if you like, or hand it to another agent to tidy up, and then go back and change whatever let it through:

* **Something specific to your site**, like voice, subjects, file conventions or length, belongs in your **prompt**.
* **Something about the method**, like the keyword rules or the writing rules, belongs in the **`seo-engine` skill**, which is plain markdown you can open and edit.
* **Something about how an agent behaves overall** belongs in the **agent** itself, including which model it runs on.

Every one of those is a text edit in Orca, and every fix holds for every run afterwards. Most of the effort lands in the first week. After that it settles into a short read each morning.

## Related

<CardGroup cols={3}>
  <Card title="Shared templates" icon="copy" href="/concepts/templates">
    How copying, renaming and updating templates works.
  </Card>

  <Card title="Connected apps" icon="plug" href="/concepts/connected-apps">
    Connecting GitHub, DataForSEO and 250+ other apps.
  </Card>

  <Card title="Prompts" icon="file-lines" href="/concepts/contexts">
    Facts about the work, attached to a run.
  </Card>
</CardGroup>