seo-skills, the SKILL.md files that teach an agent to do SEO, and what a prompt cannot verify

Markdown skill files that turn an agent into an SEO operator

seo-skills is a repository of prompt-shaped documents that an AI coding agent reads to act as an SEO and marketing assistant. The framing in the documentation is direct: these are open source SEO skills for Claude Code, Cursor, Codex and any agent that reads SKILL.md files, and installing one lets the agent run daily SEO checks, fix title tags, refresh posts that slipped, buy backlinks, map search intent and write copy.

The unit of distribution is a single file. Each skill is a folder containing a SKILL.md that follows the Agent Skills spec, and the structure the documentation gives is:

bash <category>/<skill-name>/SKILL.md

So a skill is a directory named after its category and its name, containing a markdown file. The top level of the repository mirrors that taxonomy exactly, with seo/, content/, marketing/ and copywriting/ directories and nothing else but the README.

The number of skills is small and each one is described precisely. Under SEO there are five: seo-autopilot, a daily agent that runs SEO end to end with site health checks, fixes, a keyword map, articles, comparison pages, free tools, link drafts and AI answer tracking; blitz-seo, a 30-day sprint to rank one high-value page for one money keyword; seo-title-optimization, rewriting and auditing title tags, H1s and meta titles; blog-refresher, refreshing an existing post with a SERP gap analysis; and linkdr, for buying managed backlinks from LinkDR.

Under content there are two, intro for short blog intros matched to listicle, how-to or definition intent, and scribiz for transcripts, subtitles, summaries and chapters. Under marketing there are two, customer-journey and diff-marketing. Under copywriting there are two, blitz-copy and understand-customers. Eleven in total, and each is a text file rather than a program.

Installing one skill, all of them, or listing what exists

Installation goes through a command line tool called skills, invoked with npx, and the documentation gives three invocations that cover the three things you would want to do.

To install the SEO autopilot skill:

bash npx skills add Illyism/seo-skills --skill seo-autopilot

To install everything in the repository:

bash npx skills add Illyism/seo-skills

To see what is available before committing to anything:

bash npx skills add Illyism/seo-skills --list

The shape of that interface is worth noticing. The tool takes a GitHub repository, the flag names a single skill within it, and the list flag turns the same command into an inventory. That means the repository itself is the package registry, and there is no separate publish step, no npm version to track and no changelog to read before installing. A skill is a file at a path, and the path is the identifier.

The consequence for a team is that adding a skill to a project is a normal dependency-like operation, and reviewing a new skill is reading one markdown file. There is no executable to audit, no code path to trace. What you are reviewing is a set of instructions.

The documentation also points to a related repository, Illyism/dev-skills, for developer oriented skills such as AI evals, and to a browsing page at il.ly/skills where the skills are listed. The homepage is il.ly/skills, and the licence line says MIT, by Ilias Ism.

The eleven skills and the different jobs they actually do

The skill table is more useful than a feature list, because the entries describe scope rather than adjectives.

Four of them are about improving pages that already exist. seo-title-optimization rewrites and audits title tags, H1s and meta titles for rankings and click-through rate. blog-refresher refreshes an existing post with a SERP gap analysis, with the stated aim that the post outranks the pages above it. blitz-seo is a 30-day sprint aimed at ranking one high-value page for one money keyword. And seo-autopilot is the umbrella: a daily agent that runs the SEO work end to end, including site health checks, fixes, a keyword map, articles, comparison pages, free tools, link drafts and AI answer tracking.

Two of them buy things rather than write them. linkdr plans a DR-tier mix of managed backlinks from LinkDR for a given budget and sends one checkout link, which is an unusual thing for a prompt file to be able to do, and the marketing skill diff-marketing turns recent commits and merged pull requests into blog posts, launch posts, changelogs and emails.

Two are about matching intent. The content skill intro produces short blog intros with a journey teaser, matched to listicle, how-to or definition intent, and the marketing skill customer-journey maps a five-stage awareness journey with the prompts people type into Google and ChatGPT at each stage.

And two are about the copy itself. blitz-copy writes landing pages, headlines, SEO titles, cold emails and posts using a Hook, Spike, Payoff structure, and understand-customers researches customer pains and language before any writing happens, which is the one skill in the set that is explicitly about what happens before the draft.

What a SKILL.md actually is, and what it cannot do

The mechanism is the interesting part, and it is also the limit. Each skill is a markdown document following the Agent Skills spec, sitting at a predictable path, and an agent that reads SKILL.md files picks it up. The content of the file is what shapes the agent's behaviour for that task.

That has consequences in both directions. The good one is auditability. You can read a skill before installing it, you can diff it like any other file, and you can fork it and change the instructions without touching code. The skill is a prompt, and prompts are reviewable in a way that a library's behaviour is not.

The limiting one is that a skill can only do what the agent's environment and the connected services allow. A skill that ends in sending a checkout link still needs a browser and a signed-in account, and a skill that refreshes a post still needs the post in the working tree. The documentation describes what each skill does, but it does not describe credentials, network access, scheduling or how a daily agent is actually triggered, so the operational half of running an autopilot is not specified anywhere in the repository.

The linkdr entry makes the boundary concrete. It says the skill sends one checkout link, and buying a backlink tier mix for a budget is a spending decision. A prompt file can compute a plan and hand you a link, but the purchase and everything after it happen outside the file. The same applies to the AI answer tracking in seo-autopilot, which implies reaching a service whose behaviour the repository does not describe.

So the honest reading is that these are workflow descriptions with a specific vocabulary and a specific order of operations, not automations that run by themselves.

Where this collection is the wrong tool

The first wrong case is a developer who needs code, not marketing output. These skills produce search work, copy and plans. The companion repository Illyism/dev-skills is where developer oriented skills such as AI evals live, and the separation is deliberate.

The second wrong case is a site with no content to work on. blog-refresher needs an existing post, seo-title-optimization needs pages, blitz-seo needs one page worth a 30-day push, and the customer-journey and understand-customers skills need a real audience to research. Installing these on a new domain produces process rather than progress.

The third wrong case is a team that wants the results to be reproducible and accountable. A prompt file tells an agent how to think about a task, but the output depends on the model, the tools the agent has and the state of the site that day. There is no test suite, no expected output and no regression check in the repository, so a change to a skill file cannot be validated the way a change to a function can.

The fourth wrong case is anyone who expects the agentskills.io spec to cover a runtime. The spec defines the file format and the discovery path, and that is the whole of the contract. Everything else, credentials, budgets, publishing, rollback, is not in the documentation.

The fifth wrong case is treating the free checklist as an audit tool. The SEO launch checklist is described as 71 checks, each with a test you can run and a pass condition, covering crawling, page basics, speed, content, links and AI answers. That is a manual checklist delivered by signing up for a newsletter, not a scanner you can run against a staging URL.

Where a skill collection sits against a dedicated SEO tool

The alternative is a conventional SEO platform, and the difference in approach is about where the knowledge and the verification live.

A dedicated SEO platform ships its own crawler, its own index of what it found last week, and its own dashboards. It can tell you that a page's title changed on a date, that a backlink profile moved, or that a keyword group has moved position, because it stores observations over time. It is a monitoring product. Its checks are also implemented in code, so a check either passes or it does not, and the same run on the same URL gives the same answer.

A skill collection inverts that. The knowledge lives in text, delivered to an agent that already knows how to browse, read and write. There is no stored history, so a skill cannot tell you what changed since last month without being run against both states. What it can do is reason about a task in a way a fixed form cannot, which is why a skill can write a blog post that fills a specific gap and a form-based tool cannot.

The cost of that inversion is verification. A crawl report is a fact about a URL. An agent's report is a judgement about a URL, produced by a model that may be wrong, and you find out by reading what it did. For a task like rewriting a title tag, the judgement is the work. For a task like confirming that a site is crawlable, the tooling wins outright.

So the practical split is by output type. Use a tool to establish what is true about the site, and use a skill to decide what to change and to write the change.

Licensing, maintenance and the cost of adopting a prompt collection

The licence line is short: MIT, by Ilias Ism. That is the permission most teams need, and it covers the skill files themselves. It does not cover the services some skills reach. A skill that sends a checkout link for a backlink package is arranging a purchase from a third party, and the terms of that purchase are a separate matter from the licence of the file that described it. Likewise, the video transcript skill is built around Scribiz and the backlink skill around LinkDR, so using either means accepting those services' terms and pricing.

The repository is not archived and the last push was on 2026-10-15, with no GitHub releases, so there is no version tag to pin. Since a skill is addressed by path inside a repository, the practical pin is the commit, and updating means re-running the install command and reviewing what changed in the diff of the files that were added or replaced.

The upgrade cost is therefore low in tooling terms and not zero in review terms. There is no dependency to audit for vulnerabilities, and there is also no release note explaining what a skill now does differently, so a team that installed all eleven skills has to read the diffs to know whether its agent behaviour changed.

One more cost sits outside the repository. The free checklist is delivered by signing up for a newsletter, and the documentation says the subscription also adds you to that list. The checklist itself is described as 71 checks with a test and a pass condition each, and the point of offering it separately is that it works without any agent at all.

Editorial conclusion

seo-skills suits a content team that wants its agent to do SEO work in its own words, and that reads and forks the skill files before installing them, which is the whole point of the format. It does not suit anyone who needs a factual crawl report, a history of what changed, or a regression test on agent behaviour, because the repository contains no crawler, no stored observations and no test suite. Before you install anything, run the list command to see the eleven skills, read the SKILL.md of each one you intend to add, and check the terms of the services the linkdr and scribiz skills depend on, since the MIT licence covers the files and not the purchases or subscriptions behind them.

Frequently asked questions

Official sources

1. Illyism/seo-skills on GitHub
2. Issues
3. Project website
4. README