Skip to content

AGENTS.md

Latest commit

 

History

History
321 lines (253 loc) · 12.1 KB

AGENTS.md

File metadata and controls

321 lines (253 loc) · 12.1 KB
Raw

AGENTS.md

Guidelines for AI agents working in this repository.

Repository Overview

This repository contains Agent Skills for AI agents following the Agent Skills specification. Skills install to .agents/skills/ (the cross-agent standard).

Repository Structure

localseoskills/
├── briefs/
│   ├── README.md                    # Brief system overview
│   └── _templates/
│       ├── location.brief.md        # Single location template
│       └── _brand.brief.md          # Multi-location brand rollup + approval config
├── docs/
│   ├── how-local-search-works.md    # Ranking model fundamentals
│   ├── local-seo-glossary.md        # 80+ terms defined
│   └── tool-routing.md              # Task → tool decision tree
├── meta/
│   └── lessons.md                   # Living record of observed pattern changes
├── skills/
│   ├── brief/SKILL.md               # Meta skill — session state + first run setup
│   │
│   │   # Strategy skills (26) — WHAT to do
│   ├── ai-local-search/SKILL.md
│   ├── apple-business-connect/SKILL.md
│   ├── bing-places/SKILL.md
│   ├── client-deliverables/SKILL.md
│   ├── dispatch/SKILL.md
│   ├── gbp-api-automation/SKILL.md
│   ├── gbp-optimization/SKILL.md
│   ├── gbp-posts/SKILL.md
│   ├── gbp-suspension-recovery/SKILL.md
│   ├── geogrid-analysis/SKILL.md
│   ├── local-citations/SKILL.md
│   ├── local-competitor-analysis/SKILL.md
│   ├── local-content-briefs/SKILL.md
│   ├── local-content-strategy/SKILL.md
│   ├── local-keyword-research/SKILL.md
│   ├── local-landing-pages/SKILL.md
│   ├── local-link-building/SKILL.md
│   ├── local-ppc-ads/SKILL.md
│   ├── local-reporting/SKILL.md
│   ├── local-schema/SKILL.md
│   ├── local-search-ads/SKILL.md
│   ├── local-seo-audit/SKILL.md
│   ├── lsa-ads/SKILL.md
│   ├── multi-location-seo/SKILL.md
│   ├── review-management/SKILL.md
│   ├── service-area-seo/SKILL.md
│   │
│   │   # Tool skills (12) — HOW to execute in specific tools
│   ├── ahrefs-tool/SKILL.md
│   ├── brightlocal-tool/SKILL.md
│   ├── dataforseo-tool/SKILL.md
│   ├── google-analytics-tool/SKILL.md
│   ├── google-search-console-tool/SKILL.md
│   ├── local-falcon-tool/SKILL.md
│   ├── localseodata-tool/SKILL.md
│   ├── lsa-spy-tool/SKILL.md
│   ├── screaming-frog-tool/SKILL.md
│   ├── semrush-tool/SKILL.md
│   ├── serpapi-tool/SKILL.md
│   └── whitespark-tool/SKILL.md
├── specs/
│   ├── output-schema.md             # Task output file format
│   ├── approval-workflow.md         # Three-tier approval system
│   └── notification-format.md       # Slack and email notification formats
├── tasks/
│   ├── README.md                    # Task index
│   ├── m1-rankings-monitor/TASK.md
│   ├── m2-review-velocity/TASK.md
│   ├── m3-gbp-change-monitor/TASK.md
│   ├── m4-lsa-rankings-monitor/TASK.md
│   ├── m5-ai-visibility-monitor/TASK.md
│   ├── r1-weekly-report/TASK.md
│   ├── r2-monthly-client-report/TASK.md
│   ├── r3-multi-location-rollup/TASK.md
│   ├── r4-quarterly-business-review/TASK.md
│   ├── e1-gbp-post-drafts/TASK.md
│   ├── e2-review-response-drafts/TASK.md
│   ├── e3-citation-audit/TASK.md
│   ├── e4-page-content-audit/TASK.md
│   ├── p1-prospect-audit/TASK.md
│   └── p2-competitor-monitor/TASK.md
├── tools/
│   └── REGISTRY.md                  # Tool index and overlap guide
├── .gitignore
├── AGENTS.md
├── CLAUDE.md
├── CONTRIBUTING.md
├── LICENSE
├── VERSIONS.md
└── README.md

Skill Types

Strategy Skills (26)

Tell the agent what to do for a local SEO task. Reference tool categories, not specific tools. Example: local-citations defines the citation audit and fix process, then points to docs/tool-routing for tool selection.

Tool Skills (12)

Tell the agent when and how to use a specific tool, what the data means, and what to do with results. Named *-tool (e.g., localseodata-tool, local-falcon-tool). Each includes:

  • When to use this tool vs alternatives
  • Available endpoints and what they return
  • Known quirks, bugs, or workarounds
  • How to interpret results

Meta Skills (1)

Manage agent behavior and state rather than local SEO tasks directly.

brief — the most important skill in the repo. Manages persistent work state (briefs) for specific businesses and locations.

Key behaviors:

  • First Run Detection: when a user mentions a business with no existing brief, automatically runs conversational setup — asks 5 questions, runs initial audit, creates brief structure, offers to configure scheduled tasks. No manual bootstrap required.
  • Session State: creates and updates briefs during manual sessions — session log, tools run, findings, next action.
  • Scheduled Task Integration: receives output from scheduled tasks, indexes findings into the brief, keeps the brief lean while output files hold the detail.
  • Resume: when returning to a business, reads the brief and recent outputs, summarizes current state, and picks up from the last Next Action.
  • Lessons Flywheel: proposes additions to meta/lessons.md when observing behavior that contradicts skill file guidance.

See briefs/README.md for the full brief system.

Meta skills are not included in strategy or tool skill counts.

Scheduled Tasks

15 task definitions in tasks/ — one per folder, each with its own TASK.md. This architecture mirrors the skills structure: one task per folder, self-contained, individually loadable.

Each TASK.md contains:

  • Frontmatter: name, schedule, tier, skills to load, MCPs required
  • Skills section: which skills to load + fallback instruction
  • Fallback Guidance: compressed expertise for standalone operation if skills don't load
  • Verification: pre-execution checklist
  • Prompt: the full prompt to paste into Claude Code scheduled tasks
  • Output: what gets written and where

Tasks reference skills — skills provide the interpretation framework, tasks provide the execution context. A task running without its skills loaded uses the Fallback Guidance to maintain output quality.

Approval Tiers

Tier Behavior
Autonomous Runs, writes output, notifies. No human needed.
Queue (Tier 2) Drafts output, holds for approval, then executes.
Notify (Tier 3) Confirms before AND after. Used when touching third parties.

Specs

Three spec files govern how all tasks operate:

  • specs/output-schema.md — every task output file follows this format
  • specs/approval-workflow.md — defines the three approval tiers and agency config
  • specs/notification-format.md — Slack and email formats, alert thresholds

These specs are platform-agnostic. Claude-native execution uses scheduled tasks and MCP connectors. Other platforms (LSEOAgent, OpenClaw, custom) implement the same patterns using their own infrastructure.

Briefs

Briefs are persistent work state — not part of the skills, but generated during engagements. They live in briefs/ on disk (Claude Code) or in a Claude Project knowledge base (browser/desktop).

Never commit brief files to this repo. The .gitignore handles this:

briefs/*/
!briefs/_templates/
!briefs/README.md

Brief files contain real client data. Templates in briefs/_templates/ are the only brief-related files that belong in the repo.

Brief Structure

briefs/
  {brand}/
    _brand.brief.md          ← config + rollup
    {location}/
      location.brief.md      ← always current, always lean
      reports/
      scans/
      drafts/
      alerts/

Lessons

meta/lessons.md is a living document. Agents propose additions when observing behavior that diverges from skill file guidance. Humans approve in chat before the agent writes.

Lessons belong here if they are:

  • Temporal — true now, likely to change (algo behavior, GBP policy, tool quirks)
  • Exception — contradicts general skill guidance in specific circumstances
  • Emerging — new platform or signal behavior not yet in any skill file

Lessons do NOT belong here if they are:

  • Already covered in a skill file
  • A single data point without corroboration
  • General best practice (update the skill instead)

Build / Lint / Test Commands

Skills and tasks are content-only — no build step. Verify manually:

  • YAML frontmatter is valid
  • name field matches directory name exactly
  • name is 1-64 chars, lowercase alphanumeric and hyphens only
  • description is 1-1024 characters
  • For TASK.md: verify Skills, Fallback Guidance, Verification, and Prompt sections all present

Agent Skills Specification

Skills follow the Agent Skills spec.

Required Frontmatter

---
name: skill-name
description: What this skill does and when to use it. Include trigger phrases.
metadata:
  version: 1.0.0
  author: Garrett Smith
---

Frontmatter Field Constraints

Field Required Constraints
name Yes 1-64 chars, lowercase a-z, numbers, hyphens. Must match dir.
description Yes 1-1024 chars. Describe what it does and when to use it.
license No License name (default: MIT)
metadata No Key-value pairs (author, version, etc.)

Writing Style

  • Direct and instructional
  • Second person ("You are a local SEO expert")
  • Keep SKILL.md under 500 lines
  • Use H2 for main sections, H3 for subsections
  • Bold for key terms, code blocks for examples
  • Clarity over cleverness, specific over vague

Description Best Practices

Include: what the skill does, trigger phrases, related skills for scope boundaries.

Task Specification

Tasks follow the same folder-per-item pattern as skills. Each task lives in tasks/{task-id}/TASK.md.

Required Frontmatter

---
name: task-id
description: What this task does and when to load it.
schedule: frequency and time
tier: autonomous | queue (tier 2) | notify (tier 3)
skills: skill-name, skill-name
mcps: ToolName, ToolName
---

Required Sections

Every TASK.md must contain:

  1. ## Skills — which skills to load + "If unavailable, use Fallback Guidance below"
  2. ## Fallback Guidance — compressed expertise for standalone operation
  3. ## Verification — pre-execution checklist with failure handling
  4. ## Prompt — the full prompt block
  5. ## Output — what gets written and where

Git Workflow

  • New skills: feature/skill-name
  • New tasks: feature/task-id
  • Improvements: fix/skill-name-description
  • Commit format: feat: add skill-name skill / feat: add task-id task

Local SEO Domain Context

These skills encode deep local SEO expertise. Key concepts agents should understand:

  • GBP: Google Business Profile (formerly Google My Business / GMB)
  • NAP: Name, Address, Phone — must be consistent across the web
  • Map Pack / Local Pack / 3-Pack: The map + 3 business results in local SERPs
  • Geogrid: A grid of ranking checks across a geographic area
  • ARP: Average Rank Position across a geogrid
  • ATRP: Average Top Rank Position (average of top-3 positions)
  • SoLV: Share of Local Voice (% of grid points where business ranks)
  • SAB: Service Area Business (no physical storefront shown to customers)
  • LSA: Local Services Ads (pay-per-lead Google ad format)
  • Citation: A mention of a business's NAP on a third-party site
  • Brief: Persistent work state file for a specific business/location engagement
  • Tier: Approval level for scheduled task outputs (autonomous / queue / notify)