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

> Explore OpenSEO audit system skills, from technical SEO to competitor analysis. Discover 19 markdown-driven capabilities dynamically loaded into the SAM runtime.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
// 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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/samSkills.ts).
- Use **`listSkills()`** to enumerate capabilities and **`activateSkill()`** to execute workflows with validated inputs.
- Core audit functionality is implemented in [`SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/SiteAuditWorkflow.ts) and exposed through [`serverFunctions/audit.ts`](https://github.com/every-app/open-seo/blob/main/serverFunctions/audit.ts).

## Frequently Asked Questions

### What file format defines OpenSEO audit system skills?

Each skill is defined in a [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/SKILL.md) file. The [`samSkills.ts`](https://github.com/every-app/open-seo/blob/main/samSkills.ts) module automatically discovers it at build time using `import.meta.glob(".agents/skills/*/SKILL.md")`, requiring no changes to the runtime code.