# OpenSEO Agent Skills: What They Are and How to Use Them

> Discover OpenSEO agent skills: declarative markdown files that define SEO workflows and register as slash commands. Learn how to use them to automate your SEO tasks with AI agents.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: deep-dive
- Published: 2026-08-05

---

**OpenSEO agent skills are self-contained, declarative markdown files stored in `.agents/skills/` that define single SEO workflows, automatically registering as slash commands (e.g., `/seo-coach`) when loaded by compatible AI agent runtimes.**

The every-app/open-seo repository implements a modular skill system that turns complex SEO tasks into reusable, guardrailed workflows. Each skill is a plain markdown file with YAML front-matter describing the workflow steps, required MCP tool calls, and safety constraints, allowing AI agents to execute structured SEO operations without hardcoding logic into the core application.

## What Are OpenSEO Agent Skills?

OpenSEO agent skills are **declarative workflow definitions** that live under the repository folder `.agents/skills/`. Each skill consists of a [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/SKILL.md) file following a common schema:

- **YAML front-matter** containing `name` and `description` fields
- **Human-readable specifications** including the goal, tone, and step-by-step workflow
- **Guardrails** that enforce credit limits and data validation rules
- **Suggested actions** and example prompts for user interaction

For example, the `seo-coach` skill begins with `name: seo-coach` and a concise description, then outlines the interactive coaching workflow in the markdown body.

Because these files use pure markdown with structured front-matter, any AI-agent runtime supporting the OpenSEO skill format can parse and execute them without modification.

## How OpenSEO Agent Skills Work

The architecture consists of several coordinated components that transform static markdown files into executable agent capabilities.

### Skill Definition Files

Each skill is defined in a [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/SKILL.md) file located at `.agents/skills/{skill-name}/SKILL.md`. These files declare:

- The **workflow steps** (often a sequence of OpenSEO MCP calls like `whoami` → `list_projects` → `run_site_audit`)
- **Interaction patterns** defining how the agent should prompt users
- **Guardrails** such as "do not exceed credit budget" or "verify every claim against live data"

The `seo-audit` skill, for instance, specifies a one-page site audit workflow that returns a single actionable recommendation.

### Skill Loader and Registration

At startup, the skill loader (referenced in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)) scans the `.agents/skills/` directory and:

1. Parses each [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/SKILL.md) into a structured JSON model
2. Registers a **slash command** matching the skill's `name` field (e.g., `/seo-coach`)
3. Injects the workflow logic into the agent's prompt template

This registration happens automatically when the agent restarts, making skills immediately available without code changes.

### MCP Tool Integration

Skills invoke OpenSEO functionality through **MCP tool wrappers** defined in [`src/lib/auth.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth.ts) and related utilities. These thin wrappers expose APIs such as:

- `whoami` – Validates MCP connection and credentials
- `list_projects` – Retrieves available SEO projects
- `run_site_audit` – Executes technical SEO audits
- `get_backlinks_overview` – Fetches backlink data

The **prompt generator** (implemented in [`src/server/lib/just-bash-stub.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/just-bash-stub.ts)) combines the skill's goal, tone, and workflow steps with the current conversation context to produce the final system prompt sent to the LLM.

### Guardrail Enforcement

After each tool call, the **guardrail executor** (enforced by [`src/middleware/errorHandling.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/errorHandling.ts)) validates results against the skill's defined constraints. This prevents agents from exceeding credit limits, making unverified claims, or executing risky operations outside the workflow scope.

## Installing and Using OpenSEO Agent Skills

You can install skills via the command line or manual copy.

### Via NPM (Recommended)

```bash
npx skills add every-app/open-seo --skill '*'

```

This command installs all available OpenSEO skills into your agent's skill directory.

### Manual Installation

Clone the repository and copy the skill files:

```bash
git clone https://github.com/every-app/open-seo.git
mkdir -p ~/.codex/skills
cp -R open-seo/.agents/skills/* ~/.codex/skills/

```

For Claude agents, copy to `~/.claude/skills/` instead.

### Running a Skill

Once installed and the agent restarted, trigger any skill using its slash command:

```text
User: /seo-audit
Agent: I'll audit the domain you provide. What is the website URL?
User: https://example.com
Agent: (runs the workflow defined in seo-audit – whoami → list_projects → run_site_audit → …)

```

The agent automatically reads the skill definition, asks introductory questions defined under "First response", and executes the prescribed MCP tool calls.

## Creating Custom OpenSEO Agent Skills

Developers can extend the system by adding new skill definitions without modifying core code.

Create a folder under `.agents/skills/` with a [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/SKILL.md) file:

```markdown
---
name: backlink-check
description: Run a lightweight backlink overview and surface any toxic links.
---

# Backlink Check

## Goal

Identify toxic backlinks and suggest removal or disavow actions.

## Workflow

1. `whoami` – confirm MCP connection.
2. `get_backlinks_overview` – fetch the latest backlinks.
3. Filter for links with low domain authority or spam scores.
4. Return a short report with up-to-date disavow file content.

## Guardrails

- Do not exceed 5 credit units.
- Only suggest removal of links you can verify as spammy.

```

After placing the file and restarting the agent, the `/backlink-check` command becomes available immediately.

## Summary

- OpenSEO agent skills are **declarative markdown files** in `.agents/skills/` that define SEO workflows with YAML front-matter and structured specifications.
- The **skill loader** (in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)) automatically discovers and registers skills as slash commands at runtime.
- Skills invoke OpenSEO APIs through **MCP tool wrappers** ([`src/lib/auth.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth.ts)) and enforce constraints via **guardrail executors** ([`src/middleware/errorHandling.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/errorHandling.ts)).
- Installation supports both **CLI tools** (`npx skills add`) and manual copying to agent-specific directories (`~/.codex/skills/`).
- The system is **modular by design**, allowing developers to add new SEO capabilities by creating single markdown files without touching core application code.

## Frequently Asked Questions

### What file format do OpenSEO agent skills use?

OpenSEO agent skills use **markdown with YAML front-matter**. Each skill is a [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/SKILL.md) file containing metadata fields (`name`, `description`) followed by sections defining the workflow, guardrails, and example prompts. This format is human-readable while being parseable by AI agent runtimes.

### Where should I install OpenSEO skills for my agent?

Install skills to your agent's specific skills directory. For **Codex**, use `~/.codex/skills/`. For **Claude**, use `~/.claude/skills/`. Alternatively, use the CLI command `npx skills add every-app/open-seo --skill '*'` to handle installation automatically across supported platforms.

### How do guardrails work in OpenSEO agent skills?

Guardrails are rules defined in the skill's markdown that the **guardrail executor** enforces after each tool call. According to the source code in [`src/middleware/errorHandling.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/errorHandling.ts), these rules validate that responses meet credit limits, data availability requirements, and safety constraints before being shown to users.

### Can I create custom skills for internal SEO workflows?

Yes. Create a new folder in `.agents/skills/` with a [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/SKILL.md) file defining your workflow steps, required MCP calls (like `whoami` or `run_site_audit`), and guardrails. The skill loader automatically registers it as a slash command when the agent restarts, making it available for immediate use without modifying the core OpenSEO codebase.