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

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 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 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) scans the .agents/skills/ directory and:

1. Parses each 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 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) 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) 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)

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:

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:

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 file:

---
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) automatically discovers and registers skills as slash commands at runtime.
• Skills invoke OpenSEO APIs through MCP tool wrappers (src/lib/auth.ts) and enforce constraints via guardrail executors (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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}