garrettjsmith-localseo
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/garrettjsmith--localseoskills)HTML
<a href="/listings/garrettjsmith--localseoskills"><img src="/api/listings/garrettjsmith--localseoskills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Pick the path for your setup. However you install, the 39 skills end up where your agent can find them.
Claude Code (CLI, recommended)
/plugin marketplace add garrettjsmith/localseoskills /plugin install local-seo-skills@garrettjsmith-localseo
Full brief experience. Claude reads and writes `briefs/` on your filesystem, so history compounds automatically across sessions.
Installing the plugin also connects the Local SEO Data MCP server (`https://mcp.localseodata.com/mcp`). Claude Code opens a browser sign-in the first time a tool is used; no API key goes in any file. Use either the plugin or `install.sh`, not both: each installs the skills, so every skill would show up twice. If you used `install.sh` before, run `uninstall.sh` (or `uninstall.ps1`) after installing the plugin.
Claude Desktop or Claude.ai in Chrome
Open Settings → Customize → Plugins → add marketplace `garrettjsmith/localseoskills` → install **local-seo-skills**. Three clicks.
Briefs require filesystem access. In Desktop, Claude can read and write briefs in any folder you grant access to; in Claude.ai in the browser, briefs are session-scoped and you paste them back into your Project between sessions. For the full persistent-brief experience, use Claude Code (CLI).
Terminal one-liner (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.sh | bash
Windows (PowerShell)
irm https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.ps1 | iex
Claude.ai web (without Desktop)
Open Claude in Chrome and paste:
Go to github.com/garrettjsmith/localseoskills, find all the SKILL.md files, and add them to my Claude Skills or a new Project called "Local SEO Skills".
Claude handles the import. Takes 60-90 seconds. One time.
Cursor, Codex, OpenClaw, or any Agent Skills-compatible agent
npx skills add garrettjsmith/localseoskills -g
It asks which agents to install for; `-g` installs for your user rather than the current project.
Or clone it and link each skill, since agents look one folder deep:
git clone https://github.com/garrettjsmith/localseoskills.git ~/.agents/localseoskills
mkdir -p ~/.agents/skills
for d in ~/.agents/localseoskills/skills/*/; do ln -sfn "${d%/}" ~/.agents/skills/; doneSkills are platform-agnostic markdown. Any agent that reads the [Agent Skills spec](https://agentskills.io/specification.md) can use them as context.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 31 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "garrettjsmith-localseo",
- "owner": {
- "name": "Garrett Smith",
- "email": "help@localseoskills.com"
- },
- "metadata": {
- "description": "Local SEO skills and automation for AI agents.",
- "version": "1.1.0"
- },
- "plugins": [
- {
- "name": "local-seo-skills",
- "version": "1.1.0",
- "source": "./",
- "description": "39 skills for local SEO, installed as a Claude Code plugin. GBP optimization, map pack visibility, audits, citations, reviews, keywords, geogrid, AI visibility, multi-location SEO, and reporting. Includes a persistent brief system and 15 scheduled task templates.",
- "category": "seo",
- "tags": [
- "local-seo",
- "seo",
- "mcp",
- "google-business-profile",
- "map-pack",
- "geogrid",
- "ai-visibility",
- "agency",
- "smb"
- ]
- }
- ]
- }
README.md · README · 361 lines · 2 findings marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <img src="assets/cover.png" alt="Local SEO Skills" width="900"/>
- </p>
- <p align="center">
- <a href="https://github.com/garrettjsmith/localseoskills/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/garrettjsmith/localseoskills?color=16A34A"/></a>
- <a href="https://github.com/garrettjsmith/localseoskills/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/garrettjsmith/localseoskills?color=16A34A"/></a>
- <a href="https://claude.com/claude-code"><img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude%20Code-Plugin-16A34A"/></a>
- <a href="https://agentskills.io/specification.md"><img alt="Agent Skills spec" src="https://img.shields.io/badge/Agent%20Skills-spec-16A34A"/></a>
- </p>
- # Open-Source Claude SEO Tool for Local Search
- <p align="center">
- <strong>39 open-source skills that turn your AI agent into a local SEO specialist.</strong><br/>
- Connect your data tools, describe a business, and the agent audits it, monitors it, reports on it, and executes.
- </p>
- <p align="center">
- <strong>Works with:</strong>
- Claude Code · Claude Desktop · Claude.ai · Cursor · Codex · OpenClaw · Antigravity · any Agent Skills-compatible agent
- </p>
- <p align="center">
- <em>If Local SEO Skills saves you time, star the repo. It's how other practitioners find it.</em>
- </p>
- ---
- ## What Makes This Different
- Most skill libraries stop at instructions. Local SEO Skills adds the three things that turn instructions into an actual operating system for client work:
- - **Persistent briefs.** Every client and location has a living file Claude reads and updates automatically. Ask "why did rankings drop in March?" six months into an engagement and get a real answer from the history.
- - **Scheduled tasks that run while you sleep.** 15 task templates with autonomous, queue, and notify approval tiers. Monitoring, reports, drafts, and alerts keep running when your laptop is closed.
- - **A data layer built for local, not bolted on.** The default is [Local SEO Data](https://localseodata.com): 54 tools for SERP, GBP, reviews, citations, geogrid, and AI visibility through one MCP connection. Specialist tools (Ahrefs, Semrush, Local Falcon) slot in where Local SEO Data doesn't cover.
- ---
- ## Table of Contents
- - [Install](#install)
- - [Quick Start](#quick-start)
- - [What's Inside](#whats-inside)
- - [Briefs](#briefs)
- - [Scheduled Tasks](#scheduled-tasks)
- - [Default Data Source: Local SEO Data](#default-data-source-localseodata)
- - [Why This Exists](#why-this-exists)
- - [How It Works](#how-it-works)
- - [Strategy Skills](#strategy-skills)
- - [Tool Skills](#tool-skills)
- - [Foundational Docs](#foundational-docs)
- - [Community](#community)
- - [License](#license)
- ---
- ## Install
- Pick the path for your setup. However you install, the 39 skills end up where your agent can find them.
- ### Claude Code (CLI, recommended)
- ```bash
- /plugin marketplace add garrettjsmith/localseoskills
- /plugin install local-seo-skills@garrettjsmith-localseo
- ```
- Full brief experience. Claude reads and writes `briefs/` on your filesystem, so history compounds automatically across sessions.
- Installing the plugin also connects the Local SEO Data MCP server (`https://mcp.localseodata.com/mcp`). Claude Code opens a browser sign-in the first time a tool is used; no API key goes in any file. Use either the plugin or `install.sh`, not both: each installs the skills, so every skill would show up twice. If you used `install.sh` before, run `uninstall.sh` (or `uninstall.ps1`) after installing the plugin.
- ### Claude Desktop or Claude.ai in Chrome
- Open Settings → Customize → Plugins → add marketplace `garrettjsmith/localseoskills` → install **local-seo-skills**. Three clicks.
- Briefs require filesystem access. In Desktop, Claude can read and write briefs in any folder you grant access to; in Claude.ai in the browser, briefs are session-scoped and you paste them back into your Project between sessions. For the full persistent-brief experience, use Claude Code (CLI).
- ### Terminal one-liner (macOS / Linux)
- ```bash
- curl -fsSL https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 82 on GitHub
- ```
- ### Windows (PowerShell)
- ```powershell
- irm https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 88 on GitHub
- ```
- ### Claude.ai web (without Desktop)
- Open Claude in Chrome and paste:
- ```
- Go to github.com/garrettjsmith/localseoskills, find all the SKILL.md files, and
- add them to my Claude Skills or a new Project called "Local SEO Skills".
- ```
- Claude handles the import. Takes 60-90 seconds. One time.
- ### Cursor, Codex, OpenClaw, or any Agent Skills-compatible agent
- ```bash
- npx skills add garrettjsmith/localseoskills -g
- ```
- It asks which agents to install for; `-g` installs for your user rather than the current project.
- Or clone it and link each skill, since agents look one folder deep:
- ```bash
- git clone https://github.com/garrettjsmith/localseoskills.git ~/.agents/localseoskills
- mkdir -p ~/.agents/skills
- for d in ~/.agents/localseoskills/skills/*/; do ln -sfn "${d%/}" ~/.agents/skills/; done
- ```
- Skills are platform-agnostic markdown. Any agent that reads the [Agent Skills spec](https://agentskills.io/specification.md) can use them as context.
- ---
- ## Quick Start
- **Heads up on cost:** the tool skills call the [Local SEO Data](https://localseodata.com) API, which runs on paid credits. New accounts start with a free balance. Strategy skills work without it.
- Before your first audit, connect a data source. [Local SEO Data](https://localseodata.com) is the default and covers 54 tools in one MCP connection — see [Default Data Source](#default-data-source-localseodata) below for the setup link. Without a data source connected the skills still load, but the first audit will fail with a clear message telling you which MCP is missing.
- Once installed and connected, just mention any local business. Claude picks the right skills automatically.
- ```
- You: "Audit Mike's Plumbing in Buffalo"
- → brief asks 5 quick questions
- → local-seo-audit + localseodata-tool (citation_audit, reputation_audit)
- → 47 issues found · report drafted · brief initialized
- You: "Why am I not in the map pack?"
- → gbp-optimization + localseodata-tool (local_pack, business_profile)
- → top 3 issues identified · fix priority ordered
- You: "Run a geogrid scan for 'plumber near me' in Buffalo"
- → geogrid-analysis + localseodata-tool (geogrid_scan)
- → 169-point grid rendered · ARP / ATRP / SoLV computed
- You: "How do I show up in ChatGPT for local searches?"
- → ai-local-search + localseodata-tool (ai_visibility, ai_mentions)
- → 4 AI platforms scanned · mention gaps surfaced
- You: "Pick up where we left off on Keystone Insurance"
- → brief reads prior state across 3 locations
- → summary of where we stopped · asks what's next
- ```
- ---
- ## What's Inside
- - **26 strategy skills:** GBP optimization, audits, citations, reviews, keywords, geogrid, content, AI visibility, multi-location SEO, client deliverables, a dispatch router that picks the right skills for every request, and more
- - **12 tool skills:** MCP integrations for [Local SEO Data](https://localseodata.com), Local Falcon, LSA Spy, SerpAPI, Semrush, Ahrefs, BrightLocal, DataForSEO, Whitespark, Google Search Console, Google Analytics, and Screaming Frog
- - **15 scheduled task templates:** monitoring, reporting, execution, and prospecting workflows that run on Anthropic's cloud, even when your computer is off
- - **1 brief system:** persistent work state per business and location, compounding history over time
- - **3 foundational docs:** how local search works, glossary, and tool routing
- - **20 years of local SEO practice**, encoded as markdown any agent can read
- No SaaS infrastructure. No servers. Runs on tools you already have connected.
- ---
- ## Briefs
- Briefs are persistent work state for local SEO engagements. Claude creates and maintains them automatically, one per location. When you mention a business for the first time, Claude asks 5 questions, runs an initial audit, sets up the brief, and offers to configure scheduled tasks. No manual setup.
- ```
- briefs/
- keystone-insurance/
- _brand.brief.md # config + rollup across all locations
- buffalo/
- location.brief.md # always current, always lean
- reports/ # weekly, monthly, QBR
- scans/ # geogrid, citations, page audits
- drafts/ # GBP posts, review responses (awaiting approval)
- alerts/ # monitoring alerts
- ```
- After months of scheduled tasks writing to a brief, you can ask *"why did rankings drop in March?"* and get a real answer from the history.
- Briefs are gitignored. Client data never touches the repo. See [briefs/README.md](briefs/README.md) for the full system.
- ---
- ## Scheduled Tasks
- 15 task templates that turn Local SEO Skills into always-on local SEO software. Tasks run on Anthropic's cloud infrastructure. No server required, works even when your computer is off.
- ### Approval Tiers
- | Tier | How it works | Used for |
- |------|--------------|----------|
- | **Autonomous** | Runs, writes output, notifies | Monitoring, reporting, audits |
- | **Queue** | Drafts, holds for approval, then executes | GBP posts, review responses, content |
- | **Notify** | Confirms before AND after | Client emails, live GBP pushes |
- ### Task Templates
- | ID | Task | Schedule | Tier |
- |----|------|----------|------|
- | M1 | Weekly Rankings Monitor | Weekly, Monday 7am | Autonomous |
- | M2 | Review Velocity Monitor | Weekly, Monday 7am | Autonomous |
- | M3 | GBP Change Monitor | Daily, 8am | Autonomous |
- | M4 | LSA Rankings Monitor | Weekly, Monday 7am | Autonomous |
- | M5 | AI Visibility Monitor | Monthly, 1st at 8am | Autonomous |
- | E1 | GBP Post Drafts | Monthly, 1st at 8am | Queue |
- | E2 | Review Response Drafts | Weekly, Tuesday 8am | Queue |
- | E3 | Citation Audit | Quarterly, 1st of Jan/Apr/Jul/Oct | Autonomous |
- | E4 | Local Page Content Audit | Quarterly, 1st of Jan/Apr/Jul/Oct | Queue |
- | R1 | Weekly Performance Report | Weekly, Monday 8am (after M1 + M2) | Autonomous |
- | R2 | Monthly Client Report | Monthly, 1st at 9am | Notify |
- | R3 | Multi-Location Rollup | Monthly, 1st at 10am (after R2) | Autonomous |
- | R4 | Quarterly Business Review | Quarterly, 1st of Jan/Apr/Jul/Oct, 8am | Queue |
- | P1 | Prospect Audit | On demand | Autonomous |
- | P2 | Competitor Market Monitor | Monthly, 1st | Autonomous |
- See [tasks/](tasks/) for individual task files and [specs/](specs/) for the approval workflow.
- ---
- ## Default Data Source: LocalSEOData
- [Local SEO Data](https://localseodata.com) is the default data tool for Local SEO Skills. One MCP connection, 54 tools across SERP data, business intelligence, audits, reviews, citations, keywords, AI visibility, competitor analysis, and geogrid scans.
- To connect it outside the plugin, add the MCP server `https://mcp.localseodata.com/mcp` to your agent (Claude Code: `claude mcp add --transport http --scope user localseodata https://mcp.localseodata.com/mcp`; Claude Desktop: Settings → Connectors → Add custom connector). You sign in through the browser the first time a tool runs. New accounts start with a free credit balance. Cursor, Codex and other MCP clients: add it as a remote (streamable HTTP) server with the same URL.
- Upgrading from 1.0.x? The old installer wrote your API key into the server URL. `install.sh` now replaces that entry in Claude Code. For Claude Desktop, delete the `localseodata` entry from `claude_desktop_config.json` and add the connector instead.
- Other tools (Local Falcon, Ahrefs, Semrush, and the rest) are positioned as specialists for things LocalSEOData doesn't cover: geogrid trend reports, deep backlink analysis, full site crawls, and actual traffic data.
- See [docs/tool-routing.md](docs/tool-routing.md) for the full decision tree.
- ---
- ## Why This Exists
- Local SEO is a workflow problem, not a data problem. The data is already out there. What agencies and practitioners actually need is a system that remembers what happened last month, runs audits on schedule, drafts review responses, catches GBP changes, and compounds history across client engagements without stacking another SaaS subscription on top.
- Local SEO Skills is that system. Open-source markdown any agent can read.
- Built by [Garrett Smith](https://garrettsmith.com), 20+ years in SEO as practitioner, consultant, CMO, and agency owner. Built for both single-location SMBs and multi-location brands.
- ---
- ## How It Works
- ```
- Mention a business → brief handles first-run setup
- ↓ ↓
- Claude reads the brief → skills dispatch against your data tools
- ↓ ↓
- Results update the brief → scheduled tasks keep it current
- ↓
- Ask anything about the engagement; history compounds over time
- ```
- With Local SEO Skills fully configured:
- - Monitors rankings weekly and alerts you when they move
- - Monitors reviews daily and drafts responses to unanswered ones for your approval
- - Catches GBP changes immediately and flags unauthorized edits
- - Generates monthly reports and queues them for approval before they go to clients
- - Runs quarterly audits across citations, content, and competitive position
- - Builds searchable history across every engagement
- ---
- ## Strategy Skills
- | Skill | Description |
- |-------|-------------|
- | [gbp-optimization](skills/gbp-optimization) | Google Business Profile setup, optimization, and map pack visibility |
- | [gbp-posts](skills/gbp-posts) | GBP post strategy, templates, and scheduling |
- | [gbp-suspension-recovery](skills/gbp-suspension-recovery) | GBP suspension prevention and reinstatement |
- | [gbp-api-automation](skills/gbp-api-automation) | GBP API and bulk management for enterprise |
- | [geogrid-analysis](skills/geogrid-analysis) | Map pack ranking analysis using geogrid scans and ARP/ATRP/SoLV |
- | [local-seo-audit](skills/local-seo-audit) | Comprehensive local search presence audit |
- | [local-competitor-analysis](skills/local-competitor-analysis) | Local pack competitor analysis and benchmarking |
- | [local-content-briefs](skills/local-content-briefs) | Generate semantic content briefs for local SEO content |
- | [local-content-strategy](skills/local-content-strategy) | Local content strategy, topic clusters, and editorial planning |
- | [local-reporting](skills/local-reporting) | Local SEO metrics, multi-location reporting, and ROI |
- | [local-keyword-research](skills/local-keyword-research) | Local keyword research, geo-modified keywords, intent classification |
- | [client-deliverables](skills/client-deliverables) | Audit reports, proposals, scopes of work, competitive reports |
- | [local-landing-pages](skills/local-landing-pages) | Location pages, service-area pages, and local content strategy |
- | [service-area-seo](skills/service-area-seo) | SEO for service-area businesses without a storefront |
- | [review-management](skills/review-management) | Review generation, response strategy, and reputation |
- | [local-citations](skills/local-citations) | NAP consistency, citation building, and directory management |
- | [local-link-building](skills/local-link-building) | Local backlink acquisition and digital PR |
- | [local-schema](skills/local-schema) | LocalBusiness structured data and location schema |
- | [lsa-ads](skills/lsa-ads) | Google Local Services Ads (pay-per-lead, Google Guaranteed) |
- | [local-search-ads](skills/local-search-ads) | Ads inside the Google Maps local pack |
- | [local-ppc-ads](skills/local-ppc-ads) | Geographically targeted Google Ads |
- | [apple-business-connect](skills/apple-business-connect) | Apple Maps optimization and Apple Business Connect |
- | [bing-places](skills/bing-places) | Bing Maps optimization and Bing Places for Business |
- | [ai-local-search](skills/ai-local-search) | AI Overviews, ChatGPT, Gemini, Copilot for local |
- | [multi-location-seo](skills/multi-location-seo) | Managing SEO across 10-500+ locations at scale |
- | [dispatch](skills/dispatch) | Routes requests to the right skill combination |
- ---
- ## Tool Skills
- | Skill | Tool | What It Covers |
- |-------|------|----------------|
- | [localseodata-tool](skills/localseodata-tool) | **Local SEO Data** | **Default.** 54 tools: SERP data, business profiles, reviews, citations, audits, keywords, AI visibility, geogrid scans, competitor analysis |
- | [local-falcon-tool](skills/local-falcon-tool) | Local Falcon | Geogrid trend reports, recurring campaigns, Falcon Guard (GBP monitoring), AI platform scans |
- | [lsa-spy-tool](skills/lsa-spy-tool) | LSA Spy | LSA market-level ranking tracking and competitive intelligence over time |
- | [serpapi-tool](skills/serpapi-tool) | SerpAPI | Live SERP data (fallback if LocalSEOData not connected, or for non-Google engines) |
- | [semrush-tool](skills/semrush-tool) | Semrush | Advanced keyword gap analysis, Keyword Magic Tool, site audit |
- | [ahrefs-tool](skills/ahrefs-tool) | Ahrefs | Deep backlink analysis, anchor text, lost links, referring domain details |
- | [brightlocal-tool](skills/brightlocal-tool) | BrightLocal | Citation building/submission, review monitoring dashboards |
- | [dataforseo-tool](skills/dataforseo-tool) | DataForSEO | Massive bulk operations (1000+ queries), raw API for custom pipelines |
- | [whitespark-tool](skills/whitespark-tool) | Whitespark | Citation building, review generation campaigns (Reputation Builder) |
- | [google-search-console-tool](skills/google-search-console-tool) | Google Search Console | Actual organic search performance: clicks, impressions, CTR |
- | [google-analytics-tool](skills/google-analytics-tool) | Google Analytics (GA4) | Real traffic, user behavior, conversions |
- | [screaming-frog-tool](skills/screaming-frog-tool) | Screaming Frog | Full site technical crawls, custom extraction at scale |
- ---
- ## Foundational Docs
- | Doc | Description |
- |-----|-------------|
- | [how-local-search-works](docs/how-local-search-works.md) | The ranking model, how the map pack gets assembled, how citations, reviews, and links affect rankings |
- | [local-seo-glossary](docs/local-seo-glossary.md) | Every acronym and concept: ARP, ATRP, SoLV, NAP, SAB, LSA, and 80+ more |
- | [tool-routing](docs/tool-routing.md) | Which tool to use for which task: Local SEO Data as default, specialists for gaps |
- ---
- ## Community
- Join the [Discord](https://discord.gg/BFtGYWBmDw) for freelancers, consultants, and small agencies using Claude as their operating system for local SEO.
- Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the skill authoring guide.
- Issues and feature requests: [GitHub Issues](https://github.com/garrettjsmith/localseoskills/issues).
- Support: [help@localseoskills.com](mailto:help@localseoskills.com).
- ---
- ## Security & Privacy
- Vulnerability reports: see [SECURITY.md](SECURITY.md). For a private channel, use [GitHub Security Advisories](https://github.com/garrettjsmith/localseoskills/security/advisories/new).
- Data handling (what the skills read/write, what leaves your machine, what doesn't): see [PRIVACY.md](PRIVACY.md).
- Contributor guide: see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
- ---
- ## License
- MIT. See [LICENSE](LICENSE).
- Built by [Garrett Smith](https://garrettsmith.com).
install.ps1 · Bundled script · 437 lines · 1 finding marked
- # Local SEO Skills installer for Windows (PowerShell).
- #
- # Clones the repo to $HOME\.claude\skills\localseoskills, then junctions each
- # skill folder into $HOME\.claude\skills\<name> (the only depth Claude Code
- # scans) so Claude Code and any agent that reads the Agent Skills spec can
- # discover them. If a previous install exists, fetches latest and resets
- # cleanly, preserving any briefs/ directory (client data) by backing it up
- # first.
- #
- # Compatible with PowerShell 5.1 (built in to Windows 10/11) and PowerShell 7+.
- #
- # Usage (one-liner):
- # irm https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 13 on GitHub
- #
- # Or after cloning:
- # powershell -ExecutionPolicy Bypass -File localseoskills\install.ps1
- #
- # Custom install location:
- # $env:LSS_INSTALL_DIR = "C:\custom\path"
- # powershell -ExecutionPolicy Bypass -File localseoskills\install.ps1
- $ErrorActionPreference = "Stop"
- # Ensure our own Write-Host output renders UTF-8 correctly on Windows PS 5.1.
- try { [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new() } catch {}
- $RepoUrl = "https://github.com/garrettjsmith/localseoskills.git"
- # If LSS_INSTALL_DIR is set, it must be non-empty. An empty-but-set env var
- # is almost always an accident (wrapper script typo, expansion-to-nothing)
- # and silently falling through to the default would mask a real bug.
- $InstallDir = if (Test-Path Env:LSS_INSTALL_DIR) {
- if ([string]::IsNullOrWhiteSpace($env:LSS_INSTALL_DIR)) {
- Write-Host "x LSS_INSTALL_DIR is set but empty. Unset it to use the default install location." -ForegroundColor Red
- exit 1
- }
- $env:LSS_INSTALL_DIR
- } else {
- Join-Path $HOME ".claude\skills\localseoskills"
- }
- function Say($msg) { Write-Host "> $msg" -ForegroundColor Green }
- function Fail($msg) { Write-Host "x $msg" -ForegroundColor Red; exit 1 }
- function Test-SafeInstallPath {
- # Pre-install sanity guard. Install is not destructive like uninstall, but
- # an admin running `install.ps1` with $env:LSS_INSTALL_DIR pointing at a
- # system location would happily create a skills directory in
- # C:\Windows\System32 or similar. Mirror the key refusals from
- # uninstall.ps1's Test-SafePath so those locations get rejected here too.
- param([string]$Path)
- if ([string]::IsNullOrWhiteSpace($Path)) { Fail "Refusing to install to empty path." }
- if ($Path.Length -lt 10) { Fail "Refusing to install to suspiciously short path: $Path" }
- $forward = $Path -replace '\\','/'
- if ($forward -match '(^|/)\.\.(/|$)') {
- Fail "Refusing to install to path with .. traversal: $Path"
- }
- # True 8.3 short-name alias only: 1-6 base chars + tilde + digits,
- # optional 1-3 char extension. Anchored to segment boundaries so
- # legit filenames with tilde suffix (e.g. draft~1-notes.md) pass.
- if ($forward -match '(?i)(^|/)[A-Z0-9]{1,6}~[0-9]+(\.[A-Z0-9]{1,3})?(/|$)') {
- Fail "Refusing to install to 8.3 short-name path: $Path (use the long form)"
- }
- # Match any leading backslash, not just `\\`. Real-Windows regression
- # showed PowerShell 5.1 normalizes `\\?\` to `\?\` at env-var / process
- # boundaries, so `^\\\\` missed UNC / device / admin-share inputs. No
- # legitimate install path on Windows starts with a backslash.
- if ($Path -match '^\\') {
- Fail "Refusing to install to UNC, device-namespace, or backslash-rooted path: $Path"
- }
- $blocked = @(
- $env:SystemRoot,
- $env:SystemDrive,
- $env:ProgramFiles,
- ${env:ProgramFiles(x86)},
- $env:ProgramData,
- "C:\", "C:\Windows", "C:\Windows\System32", "C:\Windows\SysWOW64",
- "C:\Program Files", "C:\Program Files (x86)", "C:\ProgramData",
- "/", "/usr", "/etc", "/var", "/bin", "/sbin", "/boot", "/dev",
- "/proc", "/sys", "/Library", "/System", "/Applications", "/private"
- ) | Where-Object { $_ }
- $normalized = $Path.TrimEnd('\','/')
- foreach ($b in $blocked) {
- $bt = $b.TrimEnd('\','/')
- if ([string]::Equals($normalized, $bt, [StringComparison]::OrdinalIgnoreCase)) {
- Fail "Refusing to install to dangerous path: $Path (equals blocklisted $bt)"
- }
- if ($bt.Length -gt 0 -and $normalized.Length -gt $bt.Length) {
- $prefix = $normalized.Substring(0, $bt.Length + 1)
- if ([string]::Equals($prefix, $bt + '\', [StringComparison]::OrdinalIgnoreCase) -or
- [string]::Equals($prefix, $bt + '/', [StringComparison]::OrdinalIgnoreCase)) {
- # Allow the default /Users/<user> or C:\Users\<user> subtree by
- # deferring to the trusted-home fast-allow used by uninstall.
- $trustedHome = $null
- try { $trustedHome = [Environment]::GetFolderPath([Environment+SpecialFolder]::UserProfile) } catch {}
- if ($trustedHome) {
- $tht = $trustedHome.TrimEnd('\','/')
- if ($normalized.Length -gt $tht.Length) {
- $homePrefix = $normalized.Substring(0, $tht.Length + 1)
- if ([string]::Equals($homePrefix, $tht + '\', [StringComparison]::OrdinalIgnoreCase) -or
- [string]::Equals($homePrefix, $tht + '/', [StringComparison]::OrdinalIgnoreCase)) {
- continue
- }
- }
- }
- Fail "Refusing to install to dangerous path: $Path (nested under blocklisted $bt)"
- }
- }
- }
- }
- function Invoke-Git {
- # $Args is a PowerShell reserved automatic variable. Using $GitArgs avoids
- # shadowing and the subtle misbehavior that causes in PS 5.1.
- param([string[]]$GitArgs)
- # Under $ErrorActionPreference=Stop, PS 5.1 can treat git's progress
- # output on stderr as a terminating error even when the command
- # succeeds. Localize EAP for the duration of the call and cast each
- # record to a plain string so Write-Host never sees an ErrorRecord.
- $prev = $ErrorActionPreference
- $ErrorActionPreference = 'Continue'
- try {
- & git @GitArgs 2>&1 | ForEach-Object { Write-Host ([string]$_) }
- } finally {
- $ErrorActionPreference = $prev
- }
- if ($LASTEXITCODE -ne 0) {
- Fail ("git " + ($GitArgs -join ' ') + " failed with exit code $LASTEXITCODE")
- }
- }
- function Backup-Briefs {
- param([string]$Dir)
- $briefs = Join-Path $Dir "briefs"
- if (-not (Test-Path $briefs)) { return }
- $backupRoot = Join-Path $HOME ".claude"
- if (-not (Test-Path $backupRoot)) {
- New-Item -ItemType Directory -Path $backupRoot -Force | Out-Null
- }
- $ts = Get-Date -Format "yyyyMMdd-HHmmss"
- $dst = Join-Path $backupRoot "lss-briefs-backup-$ts"
- # Collision-safe: append a counter if the target already exists.
- $n = 1
- while (Test-Path $dst) {
- $dst = Join-Path $backupRoot "lss-briefs-backup-$ts-$n"
- $n++
- }
- Say "Backing up briefs to $dst"
- Copy-Item -Recurse -Force $briefs $dst
- }
- function Install-Fresh {
- # Build the staging directory next to $InstallDir (same volume) so
- # Move-Item doesn't hit cross-drive failures when %TEMP% is on C: and
- # $InstallDir is on D:.
- $parent = Split-Path $InstallDir -Parent
- if (-not (Test-Path $parent)) {
- New-Item -ItemType Directory -Path $parent -Force | Out-Null
- }
- $tmp = Join-Path $parent (".lss-install-" + [System.Guid]::NewGuid().ToString("N").Substring(0,8))
- New-Item -ItemType Directory -Path $tmp -Force | Out-Null
- try {
- Say "Cloning Local SEO Skills"
- # core.longpaths=true lets git clone succeed on Windows even when the
- # resolved path exceeds the legacy 260-character MAX_PATH limit.
- Invoke-Git @("-c", "core.longpaths=true", "clone", "--depth", "1", $RepoUrl, (Join-Path $tmp "localseoskills"))
- # Defense in depth: re-check before the move. The lock should already
- # prevent a concurrent process from creating $InstallDir, but verify.
- if (Test-Path $InstallDir) {
- Fail "$InstallDir appeared mid-install. Remove it and rerun."
- }
- Move-Item -Path (Join-Path $tmp "localseoskills") -Destination $InstallDir
- } finally {
- # Reset read-only bits on any .git objects that Windows would refuse
- # to delete, then clean up staging.
- if (Test-Path $tmp) {
- Get-ChildItem -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue |
- ForEach-Object {
- try {
- $_.Attributes = $_.Attributes -band (-bnot [System.IO.FileAttributes]::ReadOnly)
- } catch {}
- }
- Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue
- }
- }
- }
- function Update-Existing {
- Say "Existing install detected at $InstallDir, updating"
- # Localize $ErrorActionPreference around the bare `git` probes below.
- # Under the script-wide `Stop` preference, PS 5.1 can treat git's stderr
- # output (progress, info messages) as a terminating error even when the
- # command succeeds. Each probe is followed by a check of $LASTEXITCODE
- # or captured output, so we don't need Stop semantics during probing.
- $prevEAP = $ErrorActionPreference
- $ErrorActionPreference = 'Continue'
- try {
- # Sanity check: the existing checkout's origin must actually be this
- # repo. Without this, a misconfigured $env:LSS_INSTALL_DIR pointing
- # at an unrelated git checkout would get `git reset --hard` against
- # the WRONG origin's branch, silently destroying the user's work.
- $originUrl = (& git -C "$InstallDir" remote get-url origin 2>$null)
- $expected = @(
- $RepoUrl,
- ($RepoUrl -replace '\.git$',''),
- (($RepoUrl -replace '\.git$','') + '.git'),
- 'git@github.com:garrettjsmith/localseoskills',
- 'git@github.com:garrettjsmith/localseoskills.git',
- 'ssh://git@github.com/garrettjsmith/localseoskills',
- 'ssh://git@github.com/garrettjsmith/localseoskills.git'
- )
- if (-not $originUrl -or -not ($expected -contains $originUrl)) {
- Fail "Refusing to update: $InstallDir exists but its origin ($originUrl) is not $RepoUrl. Remove $InstallDir manually and rerun, or unset LSS_INSTALL_DIR."
- }
- # Refuse to clobber uncommitted local changes inside the install dir.
- # Covers tracked-modified (diff), staged (diff --cached), AND
- # untracked files not gitignored. Without the untracked check, a
- # user's personal note or experimental file dropped into the install
- # dir would be silently wiped by `git reset --hard`.
- # `--exclude-standard` respects .gitignore, so briefs/<client>/ and
- # .env remain invisible here.
- & git -C "$InstallDir" diff --quiet *> $null
- $dirty = ($LASTEXITCODE -ne 0)
- & git -C "$InstallDir" diff --cached --quiet *> $null
- $staged = ($LASTEXITCODE -ne 0)
- $untracked = (& git -C "$InstallDir" ls-files --others --exclude-standard 2>$null)
- if ($dirty -or $staged -or $untracked) {
- Fail "Refusing to update: $InstallDir has uncommitted or untracked files. Commit, stash, or remove them (or remove $InstallDir and rerun for a clean install)."
- }
- # Refuse to switch branches silently on a detached HEAD.
- $branch = (& git -C "$InstallDir" symbolic-ref --short HEAD 2>$null)
- if (-not $branch) {
- Fail "Refusing to update: $InstallDir is on a detached HEAD. Check out a branch first, or remove $InstallDir and rerun."
- }
- } finally {
- $ErrorActionPreference = $prevEAP
- }
- Backup-Briefs $InstallDir
- Invoke-Git @("-C", $InstallDir, "fetch", "--depth", "1", "origin", $branch)
- Invoke-Git @("-C", $InstallDir, "reset", "--hard", "origin/$branch")
- }
- # Claude Code only discovers <skills dir>\<name>\SKILL.md, one level deep, so
- # junction each skill folder out of the clone. Junctions need no admin rights.
- # Never replaces something that isn't already a junction into this clone.
- function Test-OurLink($item) {
- # A junction pointing into this install's skills folder. StartsWith, not
- # -like: profile paths can hold [ ] wildcards, and C:\Foo must not match C:\Foobar.
- # Both sides go through GetFullPath so C:/x and C:\x compare equal.
- # A target GetFullPath can't parse isn't ours.
- try {
- $root = [System.IO.Path]::GetFullPath((Join-Path $InstallDir "skills")).TrimEnd('\') + '\'
- ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -and "$($item.Target)" -and
- [System.IO.Path]::GetFullPath("$($item.Target)").StartsWith($root, [System.StringComparison]::OrdinalIgnoreCase)
- } catch { $false }
- }
- function Link-Skills {
- $skillsDir = if ($env:LSS_SKILLS_DIR) { $env:LSS_SKILLS_DIR } else { Join-Path $HOME ".claude\skills" }
- if (-not (Test-Path -LiteralPath $skillsDir)) { New-Item -ItemType Directory -Path $skillsDir -Force | Out-Null }
- # Drop junctions to skills that no longer exist in the clone (removed upstream).
- Get-ChildItem -LiteralPath $skillsDir -Force | Where-Object { (Test-OurLink $_) -and -not (Test-Path -LiteralPath "$($_.Target)") } |
- ForEach-Object { [System.IO.Directory]::Delete($_.FullName) }
- $linked = 0
- Get-ChildItem -LiteralPath (Join-Path $InstallDir "skills") -Directory | ForEach-Object {
- if (-not (Test-Path -LiteralPath (Join-Path $_.FullName "SKILL.md"))) { return }
- $target = Join-Path $skillsDir $_.Name
- # Get-Item, not Test-Path: Test-Path is false for a junction whose target is gone.
- $item = Get-Item -LiteralPath $target -Force -ErrorAction SilentlyContinue
- if ($item) {
- if (-not (Test-OurLink $item)) {
- Say "Skipping $($_.Name): $target already exists and is not from this install."
- return
- }
- [System.IO.Directory]::Delete($target)
- }
- New-Item -ItemType Junction -Path $target -Target $_.FullName | Out-Null
- $linked++
- }
- Say "Linked $linked skills into $skillsDir"
- }
- function Configure-Mcp {
- # The server signs people in with OAuth in the browser on first use, so no
- # API key is asked for or written to any config file.
- $mcpUrl = "https://mcp.localseodata.com/mcp"
- if (Get-Command claude -ErrorAction SilentlyContinue) {
- # A .cmd/.ps1 shim can throw under ErrorActionPreference=Stop; the skills
- # are already linked, so fall through to the manual step instead.
- try {
- # Earlier installers baked an API key into the URL (?key=), stored in
- # plain text in ~/.claude.json. Swap it for the sign-in URL.
- $existing = & claude mcp get localseodata 2>$null
- $found = $LASTEXITCODE -eq 0
- if ($found -and ($existing -match 'key=')) {
- foreach ($scope in "local", "project", "user") {
- & claude mcp remove localseodata --scope $scope *> $null
- }
- & claude mcp get localseodata *> $null
- if ($LASTEXITCODE -eq 0) {
- Say "Couldn't remove your old LocalSEOData entry, which has an API key in its URL. Run: claude mcp remove localseodata"
- Say "Then revoke that key at localseodata.com/dashboard/keys and rerun this script."
- return
- }
- Say "Replaced your old key-based LocalSEOData connection with browser sign-in. You can revoke that key at localseodata.com/dashboard/keys."
- $found = $false
- }
- if ($found) {
- Say "LocalSEOData already configured in Claude Code, skipping."
- return
- }
- & claude mcp add --transport http --scope user localseodata "$mcpUrl" 2>$null
- if ($LASTEXITCODE -eq 0) {
- Say "LocalSEOData added to Claude Code (all projects). You'll sign in the first time a tool runs."
- return
- }
- } catch {}
- }
- Say "To connect LocalSEOData, add this MCP server in your agent (Claude Desktop: Settings > Connectors > Add custom connector):"
- Write-Host ""
- Write-Host " $mcpUrl"
- Write-Host ""
- }
- function Main {
- if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
- Fail "git is required but not found. Install git for Windows and try again."
- }
- # The plugin already provides the skills and the data server; linking them
- # here too would show every skill twice. (Claude Code keeps one copy of the
- # data server, so only the skills would repeat.)
- if (Get-Command claude -ErrorAction SilentlyContinue) {
- $plugins = try { (& claude plugin list 2>$null) -join "`n" } catch { "" }
- if ($plugins -match 'local-seo-skills@[^\n]*(\n[^\n]*){0,4}Status:[^\n]*enabled') {
- Say "The Local SEO Skills plugin is installed, which already provides the skills and LocalSEOData. Nothing to do."
- Say "To use this script instead, uninstall the plugin first (/plugin in Claude Code)."
- Say "If you ran this script before installing the plugin, run uninstall.ps1 to remove its copies, or each skill shows up twice."
- return
- }
- }
- # Refuse system paths, UNC/device forms, 8.3 short names, and paths with
- # .. traversal BEFORE doing any filesystem work. Protects an admin-level
- # install from mistakenly creating a skills directory under Windows,
- # System32, Program Files, or other shared roots.
- Test-SafeInstallPath $InstallDir
- # Pre-flight writability check. Catches custom LSS_INSTALL_DIR pointing
- # somewhere the user can't write before git or Move-Item give cryptic
- # errors.
- $parent = Split-Path $InstallDir -Parent
- try {
- if (-not (Test-Path $parent)) {
- New-Item -ItemType Directory -Path $parent -Force -ErrorAction Stop | Out-Null
- }
- $probe = Join-Path $parent (".lss-writable-probe-" + [System.Guid]::NewGuid().ToString("N").Substring(0,8))
- # No -Force: if the 8-char GUID-suffixed probe path collides with an
- # existing file (astronomically unlikely but possible), we want the
- # collision to fail the probe rather than silently clobber. The
- # -ErrorAction Stop makes collision throw into the catch.
- New-Item -ItemType File -Path $probe -ErrorAction Stop | Out-Null
- Remove-Item -Path $probe -Force -ErrorAction SilentlyContinue
- } catch {
- Fail "$parent is not writable by this user. Set `$env:LSS_INSTALL_DIR to a user-writable path, or rerun with appropriate permissions."
- }
- # Serialize concurrent installs. New-Item -ItemType Directory fails
- # atomically when the directory exists, which gives us a POSIX-style
- # lock. Set the lock after the writability check and before any work.
- $lockPath = "$InstallDir.lock"
- $lockOwned = $false
- try {
- New-Item -ItemType Directory -Path $lockPath -ErrorAction Stop | Out-Null
- $lockOwned = $true
- } catch {
- Fail "Another install is in progress (lock at $lockPath). If stale, remove it and retry."
- }
- try {
- $gitDir = Join-Path $InstallDir ".git"
- $isGitCheckout = $false
- if (Test-Path $gitDir) {
- # Wrap in try/catch because $ErrorActionPreference=Stop turns git's
- # stderr from a corrupt-repo check into a terminating error on
- # PS 5.1. Swallow it; $isGitCheckout stays false and the next
- # branch Fails cleanly with our intended message.
- try {
- & git -C "$InstallDir" rev-parse --git-dir *> $null
- if ($LASTEXITCODE -eq 0) { $isGitCheckout = $true }
- } catch {
- # intentional: keep $isGitCheckout = $false
- }
- }
- if ($isGitCheckout) {
- Update-Existing
- } elseif (Test-Path $InstallDir) {
- Fail "$InstallDir exists and is not a clean git checkout. Remove it and rerun."
- } else {
- Install-Fresh
- }
- Link-Skills
- Say "Local SEO Skills installed."
- Configure-Mcp
- Write-Host ""
- Write-Host "Next steps:"
- Write-Host " 1. Open Claude Code or your preferred AI agent."
- Write-Host " 2. Mention any local business to get started. For example:"
- Write-Host " 'Audit Mike's Plumbing in Buffalo'"
- Write-Host " The agent will ask 5 questions, run an audit, and set up a"
- Write-Host " persistent brief for ongoing work."
- Write-Host ""
- Write-Host "Docs: https://github.com/garrettjsmith/localseoskills"
- Write-Host "Community: https://discord.gg/dBtF26Ga2a"
- } finally {
- # Only release the lock if THIS process acquired it.
- if ($lockOwned -and (Test-Path $lockPath)) {
- Remove-Item -Path $lockPath -Recurse -Force -ErrorAction SilentlyContinue
- }
- }
- }
- Main
install.sh · Bundled script · 280 lines · 1 finding marked
- #!/usr/bin/env bash
- # Local SEO Skills installer for macOS / Linux.
- #
- # Clones the repo to ~/.claude/skills/localseoskills, then links each skill
- # folder into ~/.claude/skills/<name> (the only depth Claude Code scans) so
- # Claude Code and any agent that reads the Agent Skills spec can discover
- # them. If a previous install exists, fetches latest and fast-forwards
- # cleanly, preserving any briefs/ directory (client data) by backing it up
- # first.
- #
- # Usage (curl one-liner, pipes to bash):
- # curl -fsSL https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 12 on GitHub
- #
- # Or after cloning:
- # bash localseoskills/install.sh
- #
- # Custom install location:
- # curl -fsSL <url> | LSS_INSTALL_DIR=/custom/path bash
- set -euo pipefail
- REPO_URL="https://github.com/garrettjsmith/localseoskills.git"
- INSTALL_DIR="${LSS_INSTALL_DIR:-${HOME:?HOME is not set}/.claude/skills/localseoskills}"
- SKILLS_DIR="${LSS_SKILLS_DIR:-${HOME}/.claude/skills}"
- say() {
- printf '\033[1;32m>\033[0m %s\n' "$1"
- }
- fail() {
- printf '\033[1;31mx\033[0m %s\n' "$1" >&2
- exit 1
- }
- backup_briefs() {
- local src="$1/briefs"
- [ -d "$src" ] || return 0
- local backup_root="${HOME}/.claude"
- mkdir -p "$backup_root"
- local ts
- ts="$(date +%Y%m%d-%H%M%S)"
- local dst="${backup_root}/lss-briefs-backup-${ts}"
- # Collision-safe: append a counter if the target already exists. Protects
- # against multiple backups inside the same second, which date stamps miss.
- local n=1
- while [ -e "$dst" ]; do
- dst="${backup_root}/lss-briefs-backup-${ts}-${n}"
- n=$((n + 1))
- done
- say "Backing up briefs to $dst"
- cp -a "$src" "$dst"
- }
- install_fresh() {
- _LSS_TMP="$(mktemp -d "${TMPDIR:-/tmp}/lss-install.XXXXXX")"
- say "Cloning Local SEO Skills"
- # core.longpaths=true is a no-op on macOS/Linux but prevents failures on
- # Windows if users run this via WSL or git-bash with paths over 260 chars.
- git -c core.longpaths=true clone --depth 1 "$REPO_URL" "$_LSS_TMP/localseoskills"
- # Re-check inside the critical section so concurrent runs that slipped past
- # the lock (shouldn't happen, but defense in depth) don't nest clones.
- if [ -e "$INSTALL_DIR" ]; then
- fail "$INSTALL_DIR appeared mid-install. Remove it and rerun."
- fi
- mv "$_LSS_TMP/localseoskills" "$INSTALL_DIR"
- }
- update_existing() {
- say "Existing install detected at $INSTALL_DIR, updating"
- # Sanity check: the existing checkout's origin must actually be this repo.
- # Without this, a misconfigured LSS_INSTALL_DIR pointing at an unrelated
- # git checkout would get `git reset --hard` against the WRONG origin's
- # branch, silently destroying the user's work.
- local origin_url
- origin_url="$(git -C "$INSTALL_DIR" remote get-url origin 2>/dev/null || echo '')"
- case "$origin_url" in
- "$REPO_URL"|"${REPO_URL%.git}"|"${REPO_URL%.git}.git"|\
- git@github.com:garrettjsmith/localseoskills|\
- git@github.com:garrettjsmith/localseoskills.git|\
- ssh://git@github.com/garrettjsmith/localseoskills|\
- ssh://git@github.com/garrettjsmith/localseoskills.git)
- ;;
- *)
- fail "Refusing to update: $INSTALL_DIR exists but its origin ($origin_url) is not $REPO_URL. Remove $INSTALL_DIR manually and rerun, or unset LSS_INSTALL_DIR." ;;
- esac
- # Refuse to clobber uncommitted local changes inside the install dir. Covers
- # tracked-modified (diff), staged (diff --cached), AND untracked files that
- # are not gitignored. Without the untracked check, a user's personal note or
- # experimental file dropped into the install dir would be silently wiped by
- # `git reset --hard`. The `--exclude-standard` flag respects .gitignore, so
- # briefs/<client>/ (gitignored) and .env remain invisible to this check.
- if ! git -C "$INSTALL_DIR" diff --quiet \
- || ! git -C "$INSTALL_DIR" diff --cached --quiet \
- || [ -n "$(git -C "$INSTALL_DIR" ls-files --others --exclude-standard 2>/dev/null)" ]; then
- fail "Refusing to update: $INSTALL_DIR has uncommitted or untracked files. Commit, stash, or remove them (or remove $INSTALL_DIR and rerun for a clean install)."
- fi
- # Refuse to switch branches silently on a detached HEAD.
- local branch
- if ! branch="$(git -C "$INSTALL_DIR" symbolic-ref --short HEAD 2>/dev/null)"; then
- fail "Refusing to update: $INSTALL_DIR is on a detached HEAD. Check out a branch first, or remove $INSTALL_DIR and rerun."
- fi
- backup_briefs "$INSTALL_DIR"
- if ! git -C "$INSTALL_DIR" fetch --depth 1 origin "$branch"; then
- fail "git fetch failed. Check your network connection and try again."
- fi
- if ! git -C "$INSTALL_DIR" reset --hard "origin/$branch"; then
- fail "git reset failed. Remove $INSTALL_DIR manually and rerun."
- fi
- }
- # Claude Code only discovers <skills dir>/<name>/SKILL.md, one level deep, so
- # link each skill folder out of the clone. Never replaces something that isn't
- # already a link into this clone (a user's own skill with the same name wins).
- link_skills() {
- mkdir -p "$SKILLS_DIR"
- local dir name target linked=0
- # Drop links to skills that no longer exist in the clone (removed upstream).
- for target in "$SKILLS_DIR"/*; do
- if [ -L "$target" ] && [[ "$(readlink "$target")" == "$INSTALL_DIR/skills/"* ]] && [ ! -e "$target" ]; then
- rm "$target"
- fi
- done
- for dir in "$INSTALL_DIR"/skills/*/; do
- [ -f "${dir}SKILL.md" ] || continue
- name="$(basename "$dir")"
- target="$SKILLS_DIR/$name"
- if [ -L "$target" ] && [[ "$(readlink "$target")" == "$INSTALL_DIR/skills/"* ]]; then
- rm "$target"
- elif [ -e "$target" ] || [ -L "$target" ]; then
- say "Skipping $name: $target already exists and is not from this install."
- continue
- fi
- ln -s "${dir%/}" "$target"
- linked=$((linked + 1))
- done
- say "Linked $linked skills into $SKILLS_DIR"
- }
- configure_mcp() {
- # The server signs people in with OAuth in the browser on first use, so no
- # API key is asked for or written to any config file.
- local mcp_url="https://mcp.localseodata.com/mcp"
- if command -v claude >/dev/null 2>&1; then
- # Earlier installers baked an API key into the URL (?key=), stored in
- # plain text in ~/.claude.json. Swap it for the sign-in URL.
- local existing=""
- existing="$(claude mcp get localseodata 2>/dev/null)" || existing=""
- if printf '%s' "$existing" | grep 'key=' >/dev/null; then
- local scope
- for scope in local project user; do
- claude mcp remove localseodata --scope "$scope" >/dev/null 2>&1 || true
- done
- if claude mcp get localseodata >/dev/null 2>&1; then
- say "Couldn't remove your old LocalSEOData entry, which has an API key in its URL. Run: claude mcp remove localseodata"
- say "Then revoke that key at localseodata.com/dashboard/keys and rerun this script."
- return 0
- fi
- say "Replaced your old key-based LocalSEOData connection with browser sign-in. You can revoke that key at localseodata.com/dashboard/keys."
- existing=""
- fi
- if [ -n "$existing" ]; then
- say "LocalSEOData already configured in Claude Code, skipping."
- return 0
- elif claude mcp add --transport http --scope user localseodata "$mcp_url" 2>/dev/null; then
- say "LocalSEOData added to Claude Code (all projects). You'll sign in the first time a tool runs."
- return 0
- fi
- fi
- say "To connect LocalSEOData, add this MCP server in your agent (Claude Desktop: Settings > Connectors > Add custom connector):"
- printf '\n %s\n\n' "$mcp_url"
- }
- _LSS_TMP=""
- _LSS_LOCK=""
- _LSS_LOCK_OWNED=0
- cleanup() {
- [ -n "$_LSS_TMP" ] && [ -d "$_LSS_TMP" ] && rm -rf "$_LSS_TMP"
- # Only remove the lock if THIS process created it. Prevents a failing run
- # from deleting a lock that belongs to a concurrent winner.
- [ "$_LSS_LOCK_OWNED" -eq 1 ] && [ -n "$_LSS_LOCK" ] && [ -d "$_LSS_LOCK" ] && rmdir "$_LSS_LOCK" 2>/dev/null
- return 0
- }
- main() {
- command -v git >/dev/null 2>&1 || fail "git is required but not found. Install git and try again."
- # The plugin already provides the skills and the data server; linking them
- # here too would show every skill twice. (Claude Code keeps one copy of the
- # data server, so only the skills would repeat.)
- if command -v claude >/dev/null 2>&1 && claude plugin list 2>/dev/null | grep -A4 'local-seo-skills@' | grep 'Status:.*enabled' >/dev/null; then
- say "The Local SEO Skills plugin is installed, which already provides the skills and LocalSEOData. Nothing to do."
- say "To use this script instead, uninstall the plugin first (/plugin in Claude Code)."
- say "If you ran this script before installing the plugin, run uninstall.sh to remove its copies, or each skill shows up twice."
- exit 0
- fi
- # Pre-install path guard. Install is not destructive like uninstall, but
- # an admin running `install.sh` with LSS_INSTALL_DIR pointing at a system
- # root would create a skills directory there. Port the core refusals from
- # uninstall.sh so this class of mistake fails before we mkdir anything.
- case "/$INSTALL_DIR/" in
- */../*) fail "Refusing to install to path with .. traversal: $INSTALL_DIR" ;;
- esac
- if [ -L "$INSTALL_DIR" ]; then
- fail "Refusing to install into a symlink: $INSTALL_DIR"
- fi
- # Minimal blocklist (top-level only; install creates, not destroys, so the
- # full prefix+case+symlink apparatus from uninstall is overkill here). The
- # PS side has the same guard via Test-SafeInstallPath.
- case "${INSTALL_DIR%/}" in
- /|""|\
- /root|/home|/Users|\
- /usr|/etc|/var|/tmp|/bin|/sbin|/opt|/boot|/dev|/proc|/sys|/lib|/mnt|/srv|\
- /run|/media|/lost+found|/snap|/selinux|/sysroot|\
- /Library|/System|/Applications|/private|/cores|/Volumes|/Network|/.vol)
- fail "Refusing to install to system path: $INSTALL_DIR" ;;
- esac
- # Pre-flight writability check so custom LSS_INSTALL_DIR pointing somewhere
- # the user can't write (e.g. /opt/... without sudo) fails with a clear
- # message instead of a cryptic git or mv error later.
- local parent
- parent="$(dirname "$INSTALL_DIR")"
- if ! mkdir -p "$parent" 2>/dev/null; then
- fail "Cannot create $parent. Check permissions or set LSS_INSTALL_DIR to a user-writable path."
- fi
- if [ ! -w "$parent" ]; then
- fail "$parent is not writable by this user. Set LSS_INSTALL_DIR to a user-writable path, or rerun with appropriate permissions."
- fi
- # Serialize concurrent installs into the same dir. mkdir is atomic on POSIX,
- # so whichever process creates the lock dir first wins; the other aborts
- # cleanly instead of racing and nesting clones. Set trap BEFORE mkdir, and
- # only mark the lock as owned after mkdir succeeds, so a failing losing
- # process never removes the winner's lock.
- trap cleanup EXIT
- local lock_candidate="${INSTALL_DIR}.lock"
- if ! mkdir "$lock_candidate" 2>/dev/null; then
- fail "Another install is in progress (lock at $lock_candidate). If stale, remove it and retry."
- fi
- _LSS_LOCK="$lock_candidate"
- _LSS_LOCK_OWNED=1
- if [ -d "$INSTALL_DIR/.git" ] && git -C "$INSTALL_DIR" rev-parse --git-dir >/dev/null 2>&1; then
- update_existing
- elif [ -e "$INSTALL_DIR" ]; then
- fail "$INSTALL_DIR exists and is not a clean git checkout. Remove it and rerun."
- else
- install_fresh
- fi
- link_skills
- say "Local SEO Skills installed."
- configure_mcp
- cat <<'EOF'
- Next steps:
- 1. Open Claude Code or your preferred AI agent.
- 2. Mention any local business to get started. For example:
- "Audit Mike's Plumbing in Buffalo"
- The agent will ask 5 questions, run an audit, and set up a persistent
- brief for ongoing work.
- Docs: https://github.com/garrettjsmith/localseoskills
- Community: https://discord.gg/dBtF26Ga2a
- EOF
- }
- main "$@"
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.