OpenSEO Audit System Skills: A Complete Guide to the Markdown-Driven Architecture

The OpenSEO audit system exposes 19 distinct capabilities—from technical SEO audits to competitor analysis—defined as self-contained markdown files under .agents/skills/ and dynamically loaded into the SAM runtime.

The every-app/open-seo repository implements a flexible, skill-driven architecture that powers its audit capabilities. Instead of hardcoding workflows in TypeScript, the system discovers and executes open-seo audit system skills defined in simple markdown files. This guide covers every available skill, the underlying architecture, and how to interact with them programmatically.

How the OpenSEO Skill Architecture Works

Markdown-Based Skill Definitions

Each skill is a self-contained SKILL.md file located under .agents/skills/<skill-name>/. These markdown files describe inputs, validation rules, and workflows without requiring changes to the core codebase. Because skills are plain text, adding new capabilities is as simple as creating a folder and markdown file—no compilation or deployment steps are necessary.

The SAM Runtime Integration

At build time, src/server/features/sam/samSkills.ts bundles all public skills using import.meta.glob(".agents/skills/*/SKILL.md"). This pattern dynamically imports every skill into the SAM (Server-Agent-Model) runtime, exposing two primary APIs: listSkills() for enumeration and activateSkill() for execution.

Skill Activation Flow

When a client triggers an audit, the system calls activate_skill, which parses the corresponding SKILL.md, validates inputs against the defined schema, and executes the workflow using OpenSEO MCP tools such as run_site_audit, research_keywords, or whoami. The results are returned as structured data to the client.

Complete List of OpenSEO Audit System Skills

The repository currently maintains 19 public skills in the main branch:

Core SEO Capabilities

• seo-audit: Performs a full-site technical audit and produces a one-page, plain-language report.
• keyword-research: Discovers, evaluates, and tags promising keyword terms for content strategy.
• keyword-clustering: Groups related keywords into thematic clusters for content planning.
• local-seo: Develops strategies for geo-targeted "near-me" search visibility.
• link-prospecting: Finds and prioritizes link-building opportunities for outreach campaigns.

Analysis & Intelligence

• competitor-analysis: Compares a target site against its top competitors.
• competitive-landscape: Provides a broad, market-wide SEO landscape overview.
• openseo-review-web-content: Reviews and improves existing website copy for optimization.

Project Management & Development

• seo-project-setup: Initializes a new SEO project and captures business context.
• seo-coach: Offers interactive coaching for SEO best practices.
• openseo-release-notes: Auto-generates release notes for OpenSEO updates.
• create-repo-skill: Scaffolds a new skill repository from a standardized template.
• maintain-greptile-rules: Manages repository-wide Greptile static-analysis rules.
• merge-ready: Verifies that a pull request meets all merge criteria.

Utilities & Testing

• webapp-testing: Provides tools for end-to-end tests of the web UI.
• verify-local-mcp: Validates a local MCP (Model-Control-Protocol) installation.
• simple-issue-description: Generates concise issue summaries from raw logs.
• papercuts: Records minor friction points encountered during development.
• deslop: Experimental descriptive-lop language generation utilities.

Working with Skills Programmatically

The SAM client exposes methods to enumerate and execute open-seo audit system skills from your application code.

Listing Available Skills

Use the listSkills() method to retrieve all capabilities bundled into the runtime:

// Example: List all public skills (Node/TypeScript)
import { createServerClient } from "@open-seo/server";

const client = createServerClient();               // authenticated SAM client
const skills = await client.sam.listSkills();      // → array of { name, description }
console.log(skills.map(s => s.name).join(", "));

Activating a Specific Skill

Pass the skill name and required parameters to activateSkill() to trigger the workflow:

// Example: Activate the "seo-audit" skill for a domain
await client.sam.activateSkill("seo-audit", {
  domain: "example.com",
  projectId: await client.project.getOrCreateId("example.com")
});

These calls invoke the SAM runtime, which reads the corresponding SKILL.md, resolves required MCP tools, executes the workflow, and returns structured results.

Key Implementation Files

Understanding these source files provides insight into how skills are loaded and executed:

• src/server/features/sam/samSkills.ts: Bundles markdown files into SAM via import.meta.glob and exposes the listSkills and activateSkill APIs.
• src/server/workflows/SiteAuditWorkflow.ts: Implements the audit-specific workflow used by the seo-audit skill, handling the logic for run_site_audit calls.
• src/serverFunctions/audit.ts: Exposes HTTP endpoints that the front-end UI calls to trigger audit-related skills.
• .agents/skills/*/SKILL.md: Human-written skill definitions serving as the source of truth for each capability.

Summary

• 19 distinct skills are available in the OpenSEO audit system, ranging from technical SEO to project management and testing.
• Skills are defined as markdown files (SKILL.md) under .agents/skills/, making them easy to modify without code changes.
• The SAM runtime dynamically loads skills via import.meta.glob in samSkills.ts.
• Use listSkills() to enumerate capabilities and activateSkill() to execute workflows with validated inputs.
• Core audit functionality is implemented in SiteAuditWorkflow.ts and exposed through serverFunctions/audit.ts.

Frequently Asked Questions

What file format defines OpenSEO audit system skills?

Each skill is defined in a SKILL.md markdown file located under .agents/skills/<skill-name>/. These files contain the workflow definition, input schema, and capability description, allowing non-developers to modify or create new skills without touching TypeScript code.

How do I programmatically list all available skills in OpenSEO?

Import the server client and call client.sam.listSkills(), which queries the SAM runtime to return an array of skill objects containing name and description properties. This method relies on the glob pattern defined in src/server/features/sam/samSkills.ts.

What is the difference between the seo-audit and competitor-analysis skills?

The seo-audit skill performs a full-site technical audit using SiteAuditWorkflow.ts to generate plain-language reports, while competitor-analysis compares your site against specific competitors. Both use the same MCP tool infrastructure but execute different markdown-defined workflows.

Where are new skills added in the OpenSEO repository?

Create a new folder under .agents/skills/ containing a SKILL.md file. The samSkills.ts module automatically discovers it at build time using import.meta.glob(".agents/skills/*/SKILL.md"), requiring no changes to the runtime code.

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