What the agent does
The agent clones the repository into its own cloud sandbox and reads what the head already knows about each page. In a site built on daattali/beautiful-jekyll, _includes/head.html captures pagetitle from page.share-title, page.title or site.title, description from page.share-description, page.subtitle or the first words of the content, author from page.author or site.author, and img from page.share-img, page.cover-img, page.thumbnail-img or site.avatar, and writes them into og: and twitter: meta tags. It uses page.id to decide between og:type of article and website. There is no <script type="application/ld+json"> anywhere and no jekyll-seo-tag: _config.yml lists only jekyll-paginate and jekyll-sitemap, and the gemspec depends on jekyll >= 3.9.3, with Appraisals testing 3.9.4 and 4.3.3 in .github/workflows/ci.yml.
It writes one new include, _includes/structured-data.html, and calls it from head.html after the captures, so the JSON-LD and the meta tags can never disagree. On a post, where page.id is set, it emits a BlogPosting with headline from pagetitle, description, datePublished from page.date | date_to_xmlschema, dateModified from page.last-updated when a post sets it, author as a Person named from the author capture, image from img | absolute_url when there is one, keywords from page.tags, url and mainEntityOfPage from page.url | absolute_url. On the home page it emits a WebSite with name, url and description; the theme's search in _includes/search.html runs in the browser with no query URL, so no SearchAction is claimed. Other pages get a WebPage with the same name and description.
The strings are the part that breaks silently, so the agent runs every value through jsonify instead of quoting by hand: a title with a quote, an apostrophe in a subtitle, or strip_html output with an ampersand would otherwise produce invalid JSON that search engines ignore without a visible error. The include stays plain Liquid, with no plugin, because this theme is distributed as a gem and used on GitHub Pages, where a new plugin is not always available; jekyll-seo-tag would do some of this, but it would also add its own title and meta tags beside the ones head.html already writes.
Then it builds the way CI does. ci.yml runs bundle exec appraisal install and bundle exec appraisal jekyll build --future with JEKYLL_ENV=production, so the agent runs both Jekyll versions from Appraisals. It reads _site/2020-02-28-sample-markdown/index.html, the sample post with author: Bill Smith and a [test] tag, extracts the script block and parses it with Ruby's JSON.parse to prove it is valid, then does the same for the home page and the about page. It uses its browser to paste the built post into the schema.org validator and records what the validator reports, and leaves the richer checks that need a live URL to the reviewer.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add JSON-LD structured data to this Jekyll site. Read _config.yml, the gemspec and Appraisals, _includes/head.html, the layouts, a post's front matter and _includes/search.html first. Write _includes/structured-data.html using the same captures head.html already makes for title, description, author and image, and include it from head.html after those captures. Emit a BlogPosting on posts (headline, description, datePublished, dateModified when last-updated is set, author as a Person, image when there is one, keywords from tags, url and mainEntityOfPage), a WebSite on the home page without a SearchAction unless the site has a search URL, and a WebPage elsewhere. Pass every value through jsonify; use no plugin. Build with both Jekyll versions the Appraisals file names, parse the script block out of a built post, the home page and a page and check it is valid JSON, check it in the schema.org validator with your browser, paste the output in the pull request and open it.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that adds _includes/structured-data.html and one include line in _includes/head.html, with no change to _config.yml, the Gemfile or the gemspec. The description shows the JSON-LD block from the built sample post, the parse check for all three page kinds, the build output on both Jekyll versions and what the validator reported.
A reviewer compares the BlogPosting with the meta tags above it in the same built page: same headline, same description, same image. They decide two things the template cannot: whether author should carry a url for each writer, which the theme has no field for today, and whether a publisher with a logo should be added, which needs an image the site owner chooses.
They can also open the built post in Google's rich results test once it is deployed, since that tool needs a public URL; the pull request says the schema.org check was done on the built HTML.
Run it on every blog repository
A company with several Jekyll sites runs this once per repository rather than by hand. A short script on your server lists the repositories and sends one POST /o/{org}/sessions per site with this body and that repository in resources. Give each request a request_id, a UUID made with UUID v5 from the repository name, so a retried run of the script returns the session it already started instead of opening a second pull request. Set a webhook_url on the key from the console's Developers page and each run.completed event names the session; read the pull request from it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The template is a few dozen lines of Liquid; the risk is a quote in one title breaking the JSON on one page out of hundreds, or a value that disagrees with the meta tags beside it. The agent builds the whole site in its own sandbox on both Jekyll versions the theme supports, parses the output rather than eyeballing it, and checks a built page in the validator with its own browser.
The two builds, the parse checks and the validator page stay in the run's transcript at GET /o/{org}/sessions/{id}/messages, and the new include is listed with its content at GET /o/{org}/p/{project}/sessions/{id}/changes. A reviewer who wants to see what a crawler will read copies it from there.
Frequently asked questions
Why not add jekyll-seo-tag?
It would work, but it writes its own <title> and Open Graph tags beside the ones head.html already produces from share-title, share-description and share-img, and a theme shipped as a gem would gain a plugin dependency its users have to allow. One include that reuses the existing captures adds the JSON-LD and nothing else.
How are quotes and special characters in titles handled?
Every value goes through Liquid's jsonify filter, which produces a quoted, escaped JSON string. Writing "{{ title }}" by hand breaks on the first title with a double quote, and the page would carry invalid JSON that search engines drop silently.
Does the home page get a SearchAction?
Not in this theme, because its search runs in the browser from _includes/search.html and there is no results URL with a query parameter to describe. The home page gets a WebSite with name, URL and description; a site that adds a server-side search page can add the action then.
Will it build on GitHub Pages?
Yes. The include is plain Liquid with no plugin, and the agent builds it with the two Jekyll versions in Appraisals, which cover the version GitHub Pages runs. Nothing in _config.yml changes.