How to Add Custom Skills to Open-SEO: 4 Proven Methods

You can add custom skills to Open-SEO by installing the official skill library via npx skills add every-app/open-seo or manually copying Markdown skill files from the .agents/skills/ directory to your agent's local skill folder.

Open-SEO is an open-source SEO automation framework that extends AI agents like Claude Code and Codex through skills—self-contained Markdown files that define specific SEO workflows. According to the every-app/open-seo source code, these skills reside in the repository's hidden .agents/skills/ directory and can be installed through the Multi-Channel Plugin (MCP) or manual file operations.

Understanding the Open-SEO Skill Architecture

Before installing, it helps to understand how skills are structured in the codebase. In the every-app/open-seo repository, each skill is a directory containing a SKILL.md file and optional templates:

• .agents/skills/ – The root directory containing all available skills
• SKILL.md – The primary definition file containing prompts, parameters, and execution logic
• web/content/docs/skills/setup.md – Official documentation for skill installation

Skills are invoked via slash commands (e.g., /seo-audit) that trigger the agent to execute the workflow defined in the corresponding Markdown file.

Method 1: Standard Installation via MCP

The fastest way to add skills is using the standard installer, which registers the default skill set with the Multi-Channel Plugin (MCP).

npx skills add every-app/open-seo

This command installs the most common SEO skills—such as project setup and basic auditing—without overwhelming your agent with specialized workflows. It automatically configures the connection between your agent and the Open-SEO MCP.

Method 2: Install the Complete Skill Library

For access to every available workflow, including niche SEO operations, install all skills using the wildcard flag:

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

This pulls every SKILL.md from .agents/skills/ in the repository, giving you the full toolbox for complex automation chains.

Method 3: Agent-Specific Installation

If you run only Claude Code or only Codex and want to avoid cluttering other agent directories, specify the target agent explicitly:

# For Claude Code users

npx skills add every-app/open-seo --skill '*' --agent claude-code

# For Codex users  

npx skills add every-app/open-seo --skill '*' --agent codex

This limits the installation to the specific agent's configuration directory, keeping your development environment clean.

Method 4: Manual Copy for Customization

When you need to edit skill prompts or modify API parameters, manually copy the skill files to your agent's local skill folder:

# Create directory and copy for Claude Code

mkdir -p ~/.claude/skills
cp -R open-seo/.agents/skills/* ~/.claude/skills/

# Create directory and copy for Codex

mkdir -p ~/.codex/skills
cp -R open-seo/.agents/skills/* ~/.codex/skills/

This method gives you full control over file locations and allows you to version-control your modifications separately from the upstream repository.

Verifying and Running Your Skills

After installation, verify that the agent recognizes the new capabilities. The skills should appear in the agent's UI under the Skills section, or you can list them via:

skills list

Invoke a skill using its slash command:

• /seo-project-setup – Initializes a new SEO project context
• /seo-audit – Generates a plain-language technical audit report
• /keyword-research – Begins keyword opportunity discovery

The agent fetches traffic and backlink data through the MCP, then renders results as either an HTML report or a Markdown file you can open in a browser.

Customizing Skills for Your Workflow

Each SKILL.md file in .agents/skills/ is pure Markdown with YAML frontmatter, making customization straightforward. For example, to modify the keyword research skill to filter for low-competition terms:

1. Open ~/.claude/skills/keyword-research/SKILL.md (or your agent's equivalent path)
2. Edit the parameters section to add competition: "<0.2"
3. Save the file

The next time you run /keyword-research, the agent uses your updated logic without requiring reinstallation.

Summary

• Skills are Markdown files stored in .agents/skills/ that define SEO workflows for AI agents.
• Install via npx skills add every-app/open-seo for standard sets, or use --skill '*' for the complete library.
• Use --agent <type> flags to install only for Claude Code or Codex specifically.
• Manual copying to ~/.claude/skills/ or ~/.codex/skills/ enables local customization of prompts and parameters.
• Skills execute through slash commands after connecting the Open-SEO MCP.

Frequently Asked Questions

What file format are Open-SEO skills written in?

Open-SEO skills are written in Markdown using a SKILL.md naming convention. Each skill directory in .agents/skills/ contains the Markdown definition file and may include optional HTML templates for report generation.

Do I need to configure the MCP before adding skills?

Yes. Before any skill can execute, your agent must be linked to the Open-SEO Multi-Channel Plugin (MCP). The MCP handles data retrieval for metrics like traffic and backlinks. Refer to web/content/docs/skills/setup.md in the repository for MCP connection guidance.

Can I create new skills from scratch instead of installing existing ones?

Absolutely. You can create a new directory in your agent's skills folder (e.g., ~/.claude/skills/my-custom-skill/) and add a SKILL.md file with a YAML frontmatter header defining the title, description, and execution steps. The agent will recognize it as a native slash command immediately.

Where are skills stored when installed manually?

Manually installed skills reside in agent-specific directories: ~/.claude/skills/ for Claude Code and ~/.codex/skills/ for Codex. These locations mirror the structure of the .agents/skills/ directory in the every-app/open-seo repository.

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