Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { sort } from "remeda";
import { parse as parseYaml } from "yaml";
import { z } from "zod";
import type { SkillSource } from "agents/skills";
// Bundle the repo's public-facing skills (.agents/skills) into SAM at build
// time. Skills marked `metadata.internal: true` are repo-dev tooling and stay
// out. The glob names the dot-directory literally, so Vite matches it.
//
// The source implements the `SkillSource` interface by hand (type-only import
// above): the `agents/skills` runtime module drags in the skill-*script*
// executor graph (@cloudflare/codemode, just-bash), which a static in-memory
// manifest doesn't need.
const skillFiles = import.meta.glob<string>("/.agents/skills/*/SKILL.md", {
query: "?raw",
import: "default",
eager: true,
});
// The skill bodies are written for external MCP clients (Claude Code); this
// note reframes the surface so SAM skips the steps that don't apply in-app.
const SAM_SURFACE_NOTE = `> Surface note: you are SAM, running inside the OpenSEO app. You are already
> authenticated and scoped to the user's current project — skip any "verify the
> MCP connection", "choose a project", or skill-install steps. You have no
> local filesystem: skip local-folder and file steps.
>
> Your project context is already in your system prompt — read it there; there
> is no get_project_context tool here. Write durable facts about the business
> back with update_project_context. You have no report tools: skip any step
> that says to deliver through the seo-report skill or to save a report, and
> give the findings in chat, short and scannable.
> If a skill step needs a tool you don't have (e.g. project creation), say so
> and point the user at the app page rather than improvising.`;
type SamSkill = { name: string; description: string; body: string };
const frontmatterSchema = z.looseObject({
name: z.string().min(1),
description: z.string().min(1),
metadata: z.looseObject({ internal: z.boolean().optional() }).optional(),
});
function parseSkill(path: string, raw: string): SamSkill | null {
const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
if (!match) throw new Error(`Skill has no frontmatter: ${path}`);
const parsed = frontmatterSchema.safeParse(parseYaml(match[1]));
if (!parsed.success) {
throw new Error(`Skill frontmatter needs name + description: ${path}`);
}
const frontmatter = parsed.data;
if (frontmatter.metadata?.internal === true) return null;
// Public for `npx skills add` users but not an in-app workflow: it drafts
// GitHub issues for contributors, which SAM has no surface for.
if (frontmatter.name === "simple-issue-description") return null;
// SAM has no report tools, so the report-writing skill has nothing to drive.
if (frontmatter.name === "seo-report") return null;
return {
name: frontmatter.name,
description: frontmatter.description,
body: `${SAM_SURFACE_NOTE}\n\n${match[2].trim()}`,
};
}
// Content hash so Think's registry refreshes the catalog when a deploy ships
// changed skills (djb2 — stability matters here, not collision resistance).
function fingerprint(skills: SamSkill[]): string {
let hash = 5381;
for (const ch of skills.map((s) => `${s.name}\n${s.body}`).join("\n")) {
hash = ((hash * 33) ^ ch.charCodeAt(0)) >>> 0;
}
return hash.toString(16);
}
// The bundled skills are fixed per deploy, so parse and hash them once per
// isolate instead of on every getSkills() call.
let cachedSource: SkillSource | undefined;
export function buildSamSkillSource(): SkillSource {
if (cachedSource) return cachedSource;
const skills = sort(
Object.entries(skillFiles)
.map(([path, raw]) => parseSkill(path, raw))
.filter((skill): skill is SamSkill => skill !== null),
(a, b) => a.name.localeCompare(b.name),
);
return (cachedSource = {
id: "openseo-public-skills",
fingerprint: fingerprint(skills),
list: () =>
Promise.resolve(
skills.map(({ name, description }) => ({ name, description })),
),
load: (name) =>
Promise.resolve(skills.find((skill) => skill.name === name) ?? null),
});
}