Skip to content
Back to search

garrettjsmith-localseo

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/garrettjsmith--localseoskills/badge.svg)](/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/; done

Skills 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)

  1. {
  2. "name": "garrettjsmith-localseo",
  3. "owner": {
  4. "name": "Garrett Smith",
  5. "email": "help@localseoskills.com"
  6. },
  7. "metadata": {
  8. "description": "Local SEO skills and automation for AI agents.",
  9. "version": "1.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "local-seo-skills",
  14. "version": "1.1.0",
  15. "source": "./",
  16. "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.",
  17. "category": "seo",
  18. "tags": [
  19. "local-seo",
  20. "seo",
  21. "mcp",
  22. "google-business-profile",
  23. "map-pack",
  24. "geogrid",
  25. "ai-visibility",
  26. "agency",
  27. "smb"
  28. ]
  29. }
  30. ]
  31. }
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)

  1. <p align="center">
  2. <img src="assets/cover.png" alt="Local SEO Skills" width="900"/>
  3. </p>
  4. <p align="center">
  5. <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>
  6. <a href="https://github.com/garrettjsmith/localseoskills/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/garrettjsmith/localseoskills?color=16A34A"/></a>
  7. <a href="https://claude.com/claude-code"><img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude%20Code-Plugin-16A34A"/></a>
  8. <a href="https://agentskills.io/specification.md"><img alt="Agent Skills spec" src="https://img.shields.io/badge/Agent%20Skills-spec-16A34A"/></a>
  9. </p>
  10. # Open-Source Claude SEO Tool for Local Search
  11. <p align="center">
  12. <strong>39 open-source skills that turn your AI agent into a local SEO specialist.</strong><br/>
  13. Connect your data tools, describe a business, and the agent audits it, monitors it, reports on it, and executes.
  14. </p>
  15. <p align="center">
  16. <strong>Works with:</strong>
  17. Claude Code · Claude Desktop · Claude.ai · Cursor · Codex · OpenClaw · Antigravity · any Agent Skills-compatible agent
  18. </p>
  19. <p align="center">
  20. <em>If Local SEO Skills saves you time, star the repo. It's how other practitioners find it.</em>
  21. </p>
  22. ---
  23. ## What Makes This Different
  24. Most skill libraries stop at instructions. Local SEO Skills adds the three things that turn instructions into an actual operating system for client work:
  25. - **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.
  26. - **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.
  27. - **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.
  28. ---
  29. ## Table of Contents
  30. - [Install](#install)
  31. - [Quick Start](#quick-start)
  32. - [What's Inside](#whats-inside)
  33. - [Briefs](#briefs)
  34. - [Scheduled Tasks](#scheduled-tasks)
  35. - [Default Data Source: Local SEO Data](#default-data-source-localseodata)
  36. - [Why This Exists](#why-this-exists)
  37. - [How It Works](#how-it-works)
  38. - [Strategy Skills](#strategy-skills)
  39. - [Tool Skills](#tool-skills)
  40. - [Foundational Docs](#foundational-docs)
  41. - [Community](#community)
  42. - [License](#license)
  43. ---
  44. ## Install
  45. Pick the path for your setup. However you install, the 39 skills end up where your agent can find them.
  46. ### Claude Code (CLI, recommended)
  47. ```bash
  48. /plugin marketplace add garrettjsmith/localseoskills
  49. /plugin install local-seo-skills@garrettjsmith-localseo
  50. ```
  51. Full brief experience. Claude reads and writes `briefs/` on your filesystem, so history compounds automatically across sessions.
  52. 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.
  53. ### Claude Desktop or Claude.ai in Chrome
  54. Open Settings → Customize → Plugins → add marketplace `garrettjsmith/localseoskills` → install **local-seo-skills**. Three clicks.
  55. 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).
  56. ### Terminal one-liner (macOS / Linux)
  57. ```bash
  58. 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
  59. ```
  60. ### Windows (PowerShell)
  61. ```powershell
  62. irm https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.ps1 | iex
  63. ```
  64. ### Claude.ai web (without Desktop)
  65. Open Claude in Chrome and paste:
  66. ```
  67. Go to github.com/garrettjsmith/localseoskills, find all the SKILL.md files, and
  68. add them to my Claude Skills or a new Project called "Local SEO Skills".
  69. ```
  70. Claude handles the import. Takes 60-90 seconds. One time.
  71. ### Cursor, Codex, OpenClaw, or any Agent Skills-compatible agent
  72. ```bash
  73. npx skills add garrettjsmith/localseoskills -g
  74. ```
  75. It asks which agents to install for; `-g` installs for your user rather than the current project.
  76. Or clone it and link each skill, since agents look one folder deep:
  77. ```bash
  78. git clone https://github.com/garrettjsmith/localseoskills.git ~/.agents/localseoskills
  79. mkdir -p ~/.agents/skills
  80. for d in ~/.agents/localseoskills/skills/*/; do ln -sfn "${d%/}" ~/.agents/skills/; done
  81. ```
  82. Skills are platform-agnostic markdown. Any agent that reads the [Agent Skills spec](https://agentskills.io/specification.md) can use them as context.
  83. ---
  84. ## Quick Start
  85. **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.
  86. 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.
  87. Once installed and connected, just mention any local business. Claude picks the right skills automatically.
  88. ```
  89. You: "Audit Mike's Plumbing in Buffalo"
  90. → brief asks 5 quick questions
  91. → local-seo-audit + localseodata-tool (citation_audit, reputation_audit)
  92. → 47 issues found · report drafted · brief initialized
  93. You: "Why am I not in the map pack?"
  94. → gbp-optimization + localseodata-tool (local_pack, business_profile)
  95. → top 3 issues identified · fix priority ordered
  96. You: "Run a geogrid scan for 'plumber near me' in Buffalo"
  97. → geogrid-analysis + localseodata-tool (geogrid_scan)
  98. → 169-point grid rendered · ARP / ATRP / SoLV computed
  99. You: "How do I show up in ChatGPT for local searches?"
  100. → ai-local-search + localseodata-tool (ai_visibility, ai_mentions)
  101. → 4 AI platforms scanned · mention gaps surfaced
  102. You: "Pick up where we left off on Keystone Insurance"
  103. → brief reads prior state across 3 locations
  104. → summary of where we stopped · asks what's next
  105. ```
  106. ---
  107. ## What's Inside
  108. - **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
  109. - **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
  110. - **15 scheduled task templates:** monitoring, reporting, execution, and prospecting workflows that run on Anthropic's cloud, even when your computer is off
  111. - **1 brief system:** persistent work state per business and location, compounding history over time
  112. - **3 foundational docs:** how local search works, glossary, and tool routing
  113. - **20 years of local SEO practice**, encoded as markdown any agent can read
  114. No SaaS infrastructure. No servers. Runs on tools you already have connected.
  115. ---
  116. ## Briefs
  117. 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.
  118. ```
  119. briefs/
  120. keystone-insurance/
  121. _brand.brief.md # config + rollup across all locations
  122. buffalo/
  123. location.brief.md # always current, always lean
  124. reports/ # weekly, monthly, QBR
  125. scans/ # geogrid, citations, page audits
  126. drafts/ # GBP posts, review responses (awaiting approval)
  127. alerts/ # monitoring alerts
  128. ```
  129. 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.
  130. Briefs are gitignored. Client data never touches the repo. See [briefs/README.md](briefs/README.md) for the full system.
  131. ---
  132. ## Scheduled Tasks
  133. 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.
  134. ### Approval Tiers
  135. | Tier | How it works | Used for |
  136. |------|--------------|----------|
  137. | **Autonomous** | Runs, writes output, notifies | Monitoring, reporting, audits |
  138. | **Queue** | Drafts, holds for approval, then executes | GBP posts, review responses, content |
  139. | **Notify** | Confirms before AND after | Client emails, live GBP pushes |
  140. ### Task Templates
  141. | ID | Task | Schedule | Tier |
  142. |----|------|----------|------|
  143. | M1 | Weekly Rankings Monitor | Weekly, Monday 7am | Autonomous |
  144. | M2 | Review Velocity Monitor | Weekly, Monday 7am | Autonomous |
  145. | M3 | GBP Change Monitor | Daily, 8am | Autonomous |
  146. | M4 | LSA Rankings Monitor | Weekly, Monday 7am | Autonomous |
  147. | M5 | AI Visibility Monitor | Monthly, 1st at 8am | Autonomous |
  148. | E1 | GBP Post Drafts | Monthly, 1st at 8am | Queue |
  149. | E2 | Review Response Drafts | Weekly, Tuesday 8am | Queue |
  150. | E3 | Citation Audit | Quarterly, 1st of Jan/Apr/Jul/Oct | Autonomous |
  151. | E4 | Local Page Content Audit | Quarterly, 1st of Jan/Apr/Jul/Oct | Queue |
  152. | R1 | Weekly Performance Report | Weekly, Monday 8am (after M1 + M2) | Autonomous |
  153. | R2 | Monthly Client Report | Monthly, 1st at 9am | Notify |
  154. | R3 | Multi-Location Rollup | Monthly, 1st at 10am (after R2) | Autonomous |
  155. | R4 | Quarterly Business Review | Quarterly, 1st of Jan/Apr/Jul/Oct, 8am | Queue |
  156. | P1 | Prospect Audit | On demand | Autonomous |
  157. | P2 | Competitor Market Monitor | Monthly, 1st | Autonomous |
  158. See [tasks/](tasks/) for individual task files and [specs/](specs/) for the approval workflow.
  159. ---
  160. ## Default Data Source: LocalSEOData
  161. [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.
  162. 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.
  163. 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.
  164. 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.
  165. See [docs/tool-routing.md](docs/tool-routing.md) for the full decision tree.
  166. ---
  167. ## Why This Exists
  168. 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.
  169. Local SEO Skills is that system. Open-source markdown any agent can read.
  170. 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.
  171. ---
  172. ## How It Works
  173. ```
  174. Mention a business → brief handles first-run setup
  175. ↓ ↓
  176. Claude reads the brief → skills dispatch against your data tools
  177. ↓ ↓
  178. Results update the brief → scheduled tasks keep it current
  179. ↓
  180. Ask anything about the engagement; history compounds over time
  181. ```
  182. With Local SEO Skills fully configured:
  183. - Monitors rankings weekly and alerts you when they move
  184. - Monitors reviews daily and drafts responses to unanswered ones for your approval
  185. - Catches GBP changes immediately and flags unauthorized edits
  186. - Generates monthly reports and queues them for approval before they go to clients
  187. - Runs quarterly audits across citations, content, and competitive position
  188. - Builds searchable history across every engagement
  189. ---
  190. ## Strategy Skills
  191. | Skill | Description |
  192. |-------|-------------|
  193. | [gbp-optimization](skills/gbp-optimization) | Google Business Profile setup, optimization, and map pack visibility |
  194. | [gbp-posts](skills/gbp-posts) | GBP post strategy, templates, and scheduling |
  195. | [gbp-suspension-recovery](skills/gbp-suspension-recovery) | GBP suspension prevention and reinstatement |
  196. | [gbp-api-automation](skills/gbp-api-automation) | GBP API and bulk management for enterprise |
  197. | [geogrid-analysis](skills/geogrid-analysis) | Map pack ranking analysis using geogrid scans and ARP/ATRP/SoLV |
  198. | [local-seo-audit](skills/local-seo-audit) | Comprehensive local search presence audit |
  199. | [local-competitor-analysis](skills/local-competitor-analysis) | Local pack competitor analysis and benchmarking |
  200. | [local-content-briefs](skills/local-content-briefs) | Generate semantic content briefs for local SEO content |
  201. | [local-content-strategy](skills/local-content-strategy) | Local content strategy, topic clusters, and editorial planning |
  202. | [local-reporting](skills/local-reporting) | Local SEO metrics, multi-location reporting, and ROI |
  203. | [local-keyword-research](skills/local-keyword-research) | Local keyword research, geo-modified keywords, intent classification |
  204. | [client-deliverables](skills/client-deliverables) | Audit reports, proposals, scopes of work, competitive reports |
  205. | [local-landing-pages](skills/local-landing-pages) | Location pages, service-area pages, and local content strategy |
  206. | [service-area-seo](skills/service-area-seo) | SEO for service-area businesses without a storefront |
  207. | [review-management](skills/review-management) | Review generation, response strategy, and reputation |
  208. | [local-citations](skills/local-citations) | NAP consistency, citation building, and directory management |
  209. | [local-link-building](skills/local-link-building) | Local backlink acquisition and digital PR |
  210. | [local-schema](skills/local-schema) | LocalBusiness structured data and location schema |
  211. | [lsa-ads](skills/lsa-ads) | Google Local Services Ads (pay-per-lead, Google Guaranteed) |
  212. | [local-search-ads](skills/local-search-ads) | Ads inside the Google Maps local pack |
  213. | [local-ppc-ads](skills/local-ppc-ads) | Geographically targeted Google Ads |
  214. | [apple-business-connect](skills/apple-business-connect) | Apple Maps optimization and Apple Business Connect |
  215. | [bing-places](skills/bing-places) | Bing Maps optimization and Bing Places for Business |
  216. | [ai-local-search](skills/ai-local-search) | AI Overviews, ChatGPT, Gemini, Copilot for local |
  217. | [multi-location-seo](skills/multi-location-seo) | Managing SEO across 10-500+ locations at scale |
  218. | [dispatch](skills/dispatch) | Routes requests to the right skill combination |
  219. ---
  220. ## Tool Skills
  221. | Skill | Tool | What It Covers |
  222. |-------|------|----------------|
  223. | [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 |
  224. | [local-falcon-tool](skills/local-falcon-tool) | Local Falcon | Geogrid trend reports, recurring campaigns, Falcon Guard (GBP monitoring), AI platform scans |
  225. | [lsa-spy-tool](skills/lsa-spy-tool) | LSA Spy | LSA market-level ranking tracking and competitive intelligence over time |
  226. | [serpapi-tool](skills/serpapi-tool) | SerpAPI | Live SERP data (fallback if LocalSEOData not connected, or for non-Google engines) |
  227. | [semrush-tool](skills/semrush-tool) | Semrush | Advanced keyword gap analysis, Keyword Magic Tool, site audit |
  228. | [ahrefs-tool](skills/ahrefs-tool) | Ahrefs | Deep backlink analysis, anchor text, lost links, referring domain details |
  229. | [brightlocal-tool](skills/brightlocal-tool) | BrightLocal | Citation building/submission, review monitoring dashboards |
  230. | [dataforseo-tool](skills/dataforseo-tool) | DataForSEO | Massive bulk operations (1000+ queries), raw API for custom pipelines |
  231. | [whitespark-tool](skills/whitespark-tool) | Whitespark | Citation building, review generation campaigns (Reputation Builder) |
  232. | [google-search-console-tool](skills/google-search-console-tool) | Google Search Console | Actual organic search performance: clicks, impressions, CTR |
  233. | [google-analytics-tool](skills/google-analytics-tool) | Google Analytics (GA4) | Real traffic, user behavior, conversions |
  234. | [screaming-frog-tool](skills/screaming-frog-tool) | Screaming Frog | Full site technical crawls, custom extraction at scale |
  235. ---
  236. ## Foundational Docs
  237. | Doc | Description |
  238. |-----|-------------|
  239. | [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 |
  240. | [local-seo-glossary](docs/local-seo-glossary.md) | Every acronym and concept: ARP, ATRP, SoLV, NAP, SAB, LSA, and 80+ more |
  241. | [tool-routing](docs/tool-routing.md) | Which tool to use for which task: Local SEO Data as default, specialists for gaps |
  242. ---
  243. ## Community
  244. Join the [Discord](https://discord.gg/BFtGYWBmDw) for freelancers, consultants, and small agencies using Claude as their operating system for local SEO.
  245. Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the skill authoring guide.
  246. Issues and feature requests: [GitHub Issues](https://github.com/garrettjsmith/localseoskills/issues).
  247. Support: [help@localseoskills.com](mailto:help@localseoskills.com).
  248. ---
  249. ## Security & Privacy
  250. Vulnerability reports: see [SECURITY.md](SECURITY.md). For a private channel, use [GitHub Security Advisories](https://github.com/garrettjsmith/localseoskills/security/advisories/new).
  251. Data handling (what the skills read/write, what leaves your machine, what doesn't): see [PRIVACY.md](PRIVACY.md).
  252. Contributor guide: see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
  253. ---
  254. ## License
  255. MIT. See [LICENSE](LICENSE).
  256. Built by [Garrett Smith](https://garrettsmith.com).
install.ps1 · Bundled script · 437 lines · 1 finding marked
  1. # Local SEO Skills installer for Windows (PowerShell).
  2. #
  3. # Clones the repo to $HOME\.claude\skills\localseoskills, then junctions each
  4. # skill folder into $HOME\.claude\skills\<name> (the only depth Claude Code
  5. # scans) so Claude Code and any agent that reads the Agent Skills spec can
  6. # discover them. If a previous install exists, fetches latest and resets
  7. # cleanly, preserving any briefs/ directory (client data) by backing it up
  8. # first.
  9. #
  10. # Compatible with PowerShell 5.1 (built in to Windows 10/11) and PowerShell 7+.
  11. #
  12. # Usage (one-liner):
  13. # irm https://raw.githubusercontent.com/garrettjsmith/localseoskills/main/install.ps1 | iex
  14. #
  15. # Or after cloning:
  16. # powershell -ExecutionPolicy Bypass -File localseoskills\install.ps1
  17. #
  18. # Custom install location:
  19. # $env:LSS_INSTALL_DIR = "C:\custom\path"
  20. # powershell -ExecutionPolicy Bypass -File localseoskills\install.ps1
  21. $ErrorActionPreference = "Stop"
  22. # Ensure our own Write-Host output renders UTF-8 correctly on Windows PS 5.1.
  23. try { [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new() } catch {}
  24. $RepoUrl = "https://github.com/garrettjsmith/localseoskills.git"
  25. # If LSS_INSTALL_DIR is set, it must be non-empty. An empty-but-set env var
  26. # is almost always an accident (wrapper script typo, expansion-to-nothing)
  27. # and silently falling through to the default would mask a real bug.
  28. $InstallDir = if (Test-Path Env:LSS_INSTALL_DIR) {
  29. if ([string]::IsNullOrWhiteSpace($env:LSS_INSTALL_DIR)) {
  30. Write-Host "x LSS_INSTALL_DIR is set but empty. Unset it to use the default install location." -ForegroundColor Red
  31. exit 1
  32. }
  33. $env:LSS_INSTALL_DIR
  34. } else {
  35. Join-Path $HOME ".claude\skills\localseoskills"
  36. }
  37. function Say($msg) { Write-Host "> $msg" -ForegroundColor Green }
  38. function Fail($msg) { Write-Host "x $msg" -ForegroundColor Red; exit 1 }
  39. function Test-SafeInstallPath {
  40. # Pre-install sanity guard. Install is not destructive like uninstall, but
  41. # an admin running `install.ps1` with $env:LSS_INSTALL_DIR pointing at a
  42. # system location would happily create a skills directory in
  43. # C:\Windows\System32 or similar. Mirror the key refusals from
  44. # uninstall.ps1's Test-SafePath so those locations get rejected here too.
  45. param([string]$Path)
  46. if ([string]::IsNullOrWhiteSpace($Path)) { Fail "Refusing to install to empty path." }
  47. if ($Path.Length -lt 10) { Fail "Refusing to install to suspiciously short path: $Path" }
  48. $forward = $Path -replace '\\','/'
  49. if ($forward -match '(^|/)\.\.(/|$)') {
  50. Fail "Refusing to install to path with .. traversal: $Path"
  51. }
  52. # True 8.3 short-name alias only: 1-6 base chars + tilde + digits,
  53. # optional 1-3 char extension. Anchored to segment boundaries so
  54. # legit filenames with tilde suffix (e.g. draft~1-notes.md) pass.
  55. if ($forward -match '(?i)(^|/)[A-Z0-9]{1,6}~[0-9]+(\.[A-Z0-9]{1,3})?(/|$)') {
  56. Fail "Refusing to install to 8.3 short-name path: $Path (use the long form)"
  57. }
  58. # Match any leading backslash, not just `\\`. Real-Windows regression
  59. # showed PowerShell 5.1 normalizes `\\?\` to `\?\` at env-var / process
  60. # boundaries, so `^\\\\` missed UNC / device / admin-share inputs. No
  61. # legitimate install path on Windows starts with a backslash.
  62. if ($Path -match '^\\') {
  63. Fail "Refusing to install to UNC, device-namespace, or backslash-rooted path: $Path"
  64. }
  65. $blocked = @(
  66. $env:SystemRoot,
  67. $env:SystemDrive,
  68. $env:ProgramFiles,
  69. ${env:ProgramFiles(x86)},
  70. $env:ProgramData,
  71. "C:\", "C:\Windows", "C:\Windows\System32", "C:\Windows\SysWOW64",
  72. "C:\Program Files", "C:\Program Files (x86)", "C:\ProgramData",
  73. "/", "/usr", "/etc", "/var", "/bin", "/sbin", "/boot", "/dev",
  74. "/proc", "/sys", "/Library", "/System", "/Applications", "/private"
  75. ) | Where-Object { $_ }
  76. $normalized = $Path.TrimEnd('\','/')
  77. foreach ($b in $blocked) {
  78. $bt = $b.TrimEnd('\','/')
  79. if ([string]::Equals($normalized, $bt, [StringComparison]::OrdinalIgnoreCase)) {
  80. Fail "Refusing to install to dangerous path: $Path (equals blocklisted $bt)"
  81. }
  82. if ($bt.Length -gt 0 -and $normalized.Length -gt $bt.Length) {
  83. $prefix = $normalized.Substring(0, $bt.Length + 1)
  84. if ([string]::Equals($prefix, $bt + '\', [StringComparison]::OrdinalIgnoreCase) -or
  85. [string]::Equals($prefix, $bt + '/', [StringComparison]::OrdinalIgnoreCase)) {
  86. # Allow the default /Users/<user> or C:\Users\<user> subtree by
  87. # deferring to the trusted-home fast-allow used by uninstall.
  88. $trustedHome = $null
  89. try { $trustedHome = [Environment]::GetFolderPath([Environment+SpecialFolder]::UserProfile) } catch {}
  90. if ($trustedHome) {
  91. $tht = $trustedHome.TrimEnd('\','/')
  92. if ($normalized.Length -gt $tht.Length) {
  93. $homePrefix = $normalized.Substring(0, $tht.Length + 1)
  94. if ([string]::Equals($homePrefix, $tht + '\', [StringComparison]::OrdinalIgnoreCase) -or
  95. [string]::Equals($homePrefix, $tht + '/', [StringComparison]::OrdinalIgnoreCase)) {
  96. continue
  97. }
  98. }
  99. }
  100. Fail "Refusing to install to dangerous path: $Path (nested under blocklisted $bt)"
  101. }
  102. }
  103. }
  104. }
  105. function Invoke-Git {
  106. # $Args is a PowerShell reserved automatic variable. Using $GitArgs avoids
  107. # shadowing and the subtle misbehavior that causes in PS 5.1.
  108. param([string[]]$GitArgs)
  109. # Under $ErrorActionPreference=Stop, PS 5.1 can treat git's progress
  110. # output on stderr as a terminating error even when the command
  111. # succeeds. Localize EAP for the duration of the call and cast each
  112. # record to a plain string so Write-Host never sees an ErrorRecord.
  113. $prev = $ErrorActionPreference
  114. $ErrorActionPreference = 'Continue'
  115. try {
  116. & git @GitArgs 2>&1 | ForEach-Object { Write-Host ([string]$_) }
  117. } finally {
  118. $ErrorActionPreference = $prev
  119. }
  120. if ($LASTEXITCODE -ne 0) {
  121. Fail ("git " + ($GitArgs -join ' ') + " failed with exit code $LASTEXITCODE")
  122. }
  123. }
  124. function Backup-Briefs {
  125. param([string]$Dir)
  126. $briefs = Join-Path $Dir "briefs"
  127. if (-not (Test-Path $briefs)) { return }
  128. $backupRoot = Join-Path $HOME ".claude"
  129. if (-not (Test-Path $backupRoot)) {
  130. New-Item -ItemType Directory -Path $backupRoot -Force | Out-Null
  131. }
  132. $ts = Get-Date -Format "yyyyMMdd-HHmmss"
  133. $dst = Join-Path $backupRoot "lss-briefs-backup-$ts"
  134. # Collision-safe: append a counter if the target already exists.
  135. $n = 1
  136. while (Test-Path $dst) {
  137. $dst = Join-Path $backupRoot "lss-briefs-backup-$ts-$n"
  138. $n++
  139. }
  140. Say "Backing up briefs to $dst"
  141. Copy-Item -Recurse -Force $briefs $dst
  142. }
  143. function Install-Fresh {
  144. # Build the staging directory next to $InstallDir (same volume) so
  145. # Move-Item doesn't hit cross-drive failures when %TEMP% is on C: and
  146. # $InstallDir is on D:.
  147. $parent = Split-Path $InstallDir -Parent
  148. if (-not (Test-Path $parent)) {
  149. New-Item -ItemType Directory -Path $parent -Force | Out-Null
  150. }
  151. $tmp = Join-Path $parent (".lss-install-" + [System.Guid]::NewGuid().ToString("N").Substring(0,8))
  152. New-Item -ItemType Directory -Path $tmp -Force | Out-Null
  153. try {
  154. Say "Cloning Local SEO Skills"
  155. # core.longpaths=true lets git clone succeed on Windows even when the
  156. # resolved path exceeds the legacy 260-character MAX_PATH limit.
  157. Invoke-Git @("-c", "core.longpaths=true", "clone", "--depth", "1", $RepoUrl, (Join-Path $tmp "localseoskills"))
  158. # Defense in depth: re-check before the move. The lock should already
  159. # prevent a concurrent process from creating $InstallDir, but verify.
  160. if (Test-Path $InstallDir) {
  161. Fail "$InstallDir appeared mid-install. Remove it and rerun."
  162. }
  163. Move-Item -Path (Join-Path $tmp "localseoskills") -Destination $InstallDir
  164. } finally {
  165. # Reset read-only bits on any .git objects that Windows would refuse
  166. # to delete, then clean up staging.
  167. if (Test-Path $tmp) {
  168. Get-ChildItem -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue |
  169. ForEach-Object {
  170. try {
  171. $_.Attributes = $_.Attributes -band (-bnot [System.IO.FileAttributes]::ReadOnly)
  172. } catch {}
  173. }
  174. Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue
  175. }
  176. }
  177. }
  178. function Update-Existing {
  179. Say "Existing install detected at $InstallDir, updating"
  180. # Localize $ErrorActionPreference around the bare `git` probes below.
  181. # Under the script-wide `Stop` preference, PS 5.1 can treat git's stderr
  182. # output (progress, info messages) as a terminating error even when the
  183. # command succeeds. Each probe is followed by a check of $LASTEXITCODE
  184. # or captured output, so we don't need Stop semantics during probing.
  185. $prevEAP = $ErrorActionPreference
  186. $ErrorActionPreference = 'Continue'
  187. try {
  188. # Sanity check: the existing checkout's origin must actually be this
  189. # repo. Without this, a misconfigured $env:LSS_INSTALL_DIR pointing
  190. # at an unrelated git checkout would get `git reset --hard` against
  191. # the WRONG origin's branch, silently destroying the user's work.
  192. $originUrl = (& git -C "$InstallDir" remote get-url origin 2>$null)
  193. $expected = @(
  194. $RepoUrl,
  195. ($RepoUrl -replace '\.git$',''),
  196. (($RepoUrl -replace '\.git$','') + '.git'),
  197. 'git@github.com:garrettjsmith/localseoskills',
  198. 'git@github.com:garrettjsmith/localseoskills.git',
  199. 'ssh://git@github.com/garrettjsmith/localseoskills',
  200. 'ssh://git@github.com/garrettjsmith/localseoskills.git'
  201. )
  202. if (-not $originUrl -or -not ($expected -contains $originUrl)) {
  203. Fail "Refusing to update: $InstallDir exists but its origin ($originUrl) is not $RepoUrl. Remove $InstallDir manually and rerun, or unset LSS_INSTALL_DIR."
  204. }
  205. # Refuse to clobber uncommitted local changes inside the install dir.
  206. # Covers tracked-modified (diff), staged (diff --cached), AND
  207. # untracked files not gitignored. Without the untracked check, a
  208. # user's personal note or experimental file dropped into the install
  209. # dir would be silently wiped by `git reset --hard`.
  210. # `--exclude-standard` respects .gitignore, so briefs/<client>/ and
  211. # .env remain invisible here.
  212. & git -C "$InstallDir" diff --quiet *> $null
  213. $dirty = ($LASTEXITCODE -ne 0)
  214. & git -C "$InstallDir" diff --cached --quiet *> $null
  215. $staged = ($LASTEXITCODE -ne 0)
  216. $untracked = (& git -C "$InstallDir" ls-files --others --exclude-standard 2>$null)
  217. if ($dirty -or $staged -or $untracked) {
  218. Fail "Refusing to update: $InstallDir has uncommitted or untracked files. Commit, stash, or remove them (or remove $InstallDir and rerun for a clean install)."
  219. }
  220. # Refuse to switch branches silently on a detached HEAD.
  221. $branch = (& git -C "$InstallDir" symbolic-ref --short HEAD 2>$null)
  222. if (-not $branch) {
  223. Fail "Refusing to update: $InstallDir is on a detached HEAD. Check out a branch first, or remove $InstallDir and rerun."
  224. }
  225. } finally {
  226. $ErrorActionPreference = $prevEAP
  227. }
  228. Backup-Briefs $InstallDir
  229. Invoke-Git @("-C", $InstallDir, "fetch", "--depth", "1", "origin", $branch)
  230. Invoke-Git @("-C", $InstallDir, "reset", "--hard", "origin/$branch")
  231. }
  232. # Claude Code only discovers <skills dir>\<name>\SKILL.md, one level deep, so
  233. # junction each skill folder out of the clone. Junctions need no admin rights.
  234. # Never replaces something that isn't already a junction into this clone.
  235. function Test-OurLink($item) {
  236. # A junction pointing into this install's skills folder. StartsWith, not
  237. # -like: profile paths can hold [ ] wildcards, and C:\Foo must not match C:\Foobar.
  238. # Both sides go through GetFullPath so C:/x and C:\x compare equal.
  239. # A target GetFullPath can't parse isn't ours.
  240. try {
  241. $root = [System.IO.Path]::GetFullPath((Join-Path $InstallDir "skills")).TrimEnd('\') + '\'
  242. ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -and "$($item.Target)" -and
  243. [System.IO.Path]::GetFullPath("$($item.Target)").StartsWith($root, [System.StringComparison]::OrdinalIgnoreCase)
  244. } catch { $false }
  245. }
  246. function Link-Skills {
  247. $skillsDir = if ($env:LSS_SKILLS_DIR) { $env:LSS_SKILLS_DIR } else { Join-Path $HOME ".claude\skills" }
  248. if (-not (Test-Path -LiteralPath $skillsDir)) { New-Item -ItemType Directory -Path $skillsDir -Force | Out-Null }
  249. # Drop junctions to skills that no longer exist in the clone (removed upstream).
  250. Get-ChildItem -LiteralPath $skillsDir -Force | Where-Object { (Test-OurLink $_) -and -not (Test-Path -LiteralPath "$($_.Target)") } |
  251. ForEach-Object { [System.IO.Directory]::Delete($_.FullName) }
  252. $linked = 0
  253. Get-ChildItem -LiteralPath (Join-Path $InstallDir "skills") -Directory | ForEach-Object {
  254. if (-not (Test-Path -LiteralPath (Join-Path $_.FullName "SKILL.md"))) { return }
  255. $target = Join-Path $skillsDir $_.Name
  256. # Get-Item, not Test-Path: Test-Path is false for a junction whose target is gone.
  257. $item = Get-Item -LiteralPath $target -Force -ErrorAction SilentlyContinue
  258. if ($item) {
  259. if (-not (Test-OurLink $item)) {
  260. Say "Skipping $($_.Name): $target already exists and is not from this install."
  261. return
  262. }
  263. [System.IO.Directory]::Delete($target)
  264. }
  265. New-Item -ItemType Junction -Path $target -Target $_.FullName | Out-Null
  266. $linked++
  267. }
  268. Say "Linked $linked skills into $skillsDir"
  269. }
  270. function Configure-Mcp {
  271. # The server signs people in with OAuth in the browser on first use, so no
  272. # API key is asked for or written to any config file.
  273. $mcpUrl = "https://mcp.localseodata.com/mcp"
  274. if (Get-Command claude -ErrorAction SilentlyContinue) {
  275. # A .cmd/.ps1 shim can throw under ErrorActionPreference=Stop; the skills
  276. # are already linked, so fall through to the manual step instead.
  277. try {
  278. # Earlier installers baked an API key into the URL (?key=), stored in
  279. # plain text in ~/.claude.json. Swap it for the sign-in URL.
  280. $existing = & claude mcp get localseodata 2>$null
  281. $found = $LASTEXITCODE -eq 0
  282. if ($found -and ($existing -match 'key=')) {
  283. foreach ($scope in "local", "project", "user") {
  284. & claude mcp remove localseodata --scope $scope *> $null
  285. }
  286. & claude mcp get localseodata *> $null
  287. if ($LASTEXITCODE -eq 0) {
  288. Say "Couldn't remove your old LocalSEOData entry, which has an API key in its URL. Run: claude mcp remove localseodata"
  289. Say "Then revoke that key at localseodata.com/dashboard/keys and rerun this script."
  290. return
  291. }
  292. Say "Replaced your old key-based LocalSEOData connection with browser sign-in. You can revoke that key at localseodata.com/dashboard/keys."
  293. $found = $false
  294. }
  295. if ($found) {
  296. Say "LocalSEOData already configured in Claude Code, skipping."
  297. return
  298. }
  299. & claude mcp add --transport http --scope user localseodata "$mcpUrl" 2>$null
  300. if ($LASTEXITCODE -eq 0) {
  301. Say "LocalSEOData added to Claude Code (all projects). You'll sign in the first time a tool runs."
  302. return
  303. }
  304. } catch {}
  305. }
  306. Say "To connect LocalSEOData, add this MCP server in your agent (Claude Desktop: Settings > Connectors > Add custom connector):"
  307. Write-Host ""
  308. Write-Host " $mcpUrl"
  309. Write-Host ""
  310. }
  311. function Main {
  312. if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
  313. Fail "git is required but not found. Install git for Windows and try again."
  314. }
  315. # The plugin already provides the skills and the data server; linking them
  316. # here too would show every skill twice. (Claude Code keeps one copy of the
  317. # data server, so only the skills would repeat.)
  318. if (Get-Command claude -ErrorAction SilentlyContinue) {
  319. $plugins = try { (& claude plugin list 2>$null) -join "`n" } catch { "" }
  320. if ($plugins -match 'local-seo-skills@[^\n]*(\n[^\n]*){0,4}Status:[^\n]*enabled') {
  321. Say "The Local SEO Skills plugin is installed, which already provides the skills and LocalSEOData. Nothing to do."
  322. Say "To use this script instead, uninstall the plugin first (/plugin in Claude Code)."
  323. Say "If you ran this script before installing the plugin, run uninstall.ps1 to remove its copies, or each skill shows up twice."
  324. return
  325. }
  326. }
  327. # Refuse system paths, UNC/device forms, 8.3 short names, and paths with
  328. # .. traversal BEFORE doing any filesystem work. Protects an admin-level
  329. # install from mistakenly creating a skills directory under Windows,
  330. # System32, Program Files, or other shared roots.
  331. Test-SafeInstallPath $InstallDir
  332. # Pre-flight writability check. Catches custom LSS_INSTALL_DIR pointing
  333. # somewhere the user can't write before git or Move-Item give cryptic
  334. # errors.
  335. $parent = Split-Path $InstallDir -Parent
  336. try {
  337. if (-not (Test-Path $parent)) {
  338. New-Item -ItemType Directory -Path $parent -Force -ErrorAction Stop | Out-Null
  339. }
  340. $probe = Join-Path $parent (".lss-writable-probe-" + [System.Guid]::NewGuid().ToString("N").Substring(0,8))
  341. # No -Force: if the 8-char GUID-suffixed probe path collides with an
  342. # existing file (astronomically unlikely but possible), we want the
  343. # collision to fail the probe rather than silently clobber. The
  344. # -ErrorAction Stop makes collision throw into the catch.
  345. New-Item -ItemType File -Path $probe -ErrorAction Stop | Out-Null
  346. Remove-Item -Path $probe -Force -ErrorAction SilentlyContinue
  347. } catch {
  348. Fail "$parent is not writable by this user. Set `$env:LSS_INSTALL_DIR to a user-writable path, or rerun with appropriate permissions."
  349. }
  350. # Serialize concurrent installs. New-Item -ItemType Directory fails
  351. # atomically when the directory exists, which gives us a POSIX-style
  352. # lock. Set the lock after the writability check and before any work.
  353. $lockPath = "$InstallDir.lock"
  354. $lockOwned = $false
  355. try {
  356. New-Item -ItemType Directory -Path $lockPath -ErrorAction Stop | Out-Null
  357. $lockOwned = $true
  358. } catch {
  359. Fail "Another install is in progress (lock at $lockPath). If stale, remove it and retry."
  360. }
  361. try {
  362. $gitDir = Join-Path $InstallDir ".git"
  363. $isGitCheckout = $false
  364. if (Test-Path $gitDir) {
  365. # Wrap in try/catch because $ErrorActionPreference=Stop turns git's
  366. # stderr from a corrupt-repo check into a terminating error on
  367. # PS 5.1. Swallow it; $isGitCheckout stays false and the next
  368. # branch Fails cleanly with our intended message.
  369. try {
  370. & git -C "$InstallDir" rev-parse --git-dir *> $null
  371. if ($LASTEXITCODE -eq 0) { $isGitCheckout = $true }
  372. } catch {
  373. # intentional: keep $isGitCheckout = $false
  374. }
  375. }
  376. if ($isGitCheckout) {
  377. Update-Existing
  378. } elseif (Test-Path $InstallDir) {
  379. Fail "$InstallDir exists and is not a clean git checkout. Remove it and rerun."
  380. } else {
  381. Install-Fresh
  382. }
  383. Link-Skills
  384. Say "Local SEO Skills installed."
  385. Configure-Mcp
  386. Write-Host ""
  387. Write-Host "Next steps:"
  388. Write-Host " 1. Open Claude Code or your preferred AI agent."
  389. Write-Host " 2. Mention any local business to get started. For example:"
  390. Write-Host " 'Audit Mike's Plumbing in Buffalo'"
  391. Write-Host " The agent will ask 5 questions, run an audit, and set up a"
  392. Write-Host " persistent brief for ongoing work."
  393. Write-Host ""
  394. Write-Host "Docs: https://github.com/garrettjsmith/localseoskills"
  395. Write-Host "Community: https://discord.gg/dBtF26Ga2a"
  396. } finally {
  397. # Only release the lock if THIS process acquired it.
  398. if ($lockOwned -and (Test-Path $lockPath)) {
  399. Remove-Item -Path $lockPath -Recurse -Force -ErrorAction SilentlyContinue
  400. }
  401. }
  402. }
  403. Main
install.sh · Bundled script · 280 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # Local SEO Skills installer for macOS / Linux.
  3. #
  4. # Clones the repo to ~/.claude/skills/localseoskills, then links each skill
  5. # folder into ~/.claude/skills/<name> (the only depth Claude Code scans) so
  6. # Claude Code and any agent that reads the Agent Skills spec can discover
  7. # them. If a previous install exists, fetches latest and fast-forwards
  8. # cleanly, preserving any briefs/ directory (client data) by backing it up
  9. # first.
  10. #
  11. # Usage (curl one-liner, pipes to bash):
  12. # 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
  13. #
  14. # Or after cloning:
  15. # bash localseoskills/install.sh
  16. #
  17. # Custom install location:
  18. # curl -fsSL <url> | LSS_INSTALL_DIR=/custom/path bash
  19. set -euo pipefail
  20. REPO_URL="https://github.com/garrettjsmith/localseoskills.git"
  21. INSTALL_DIR="${LSS_INSTALL_DIR:-${HOME:?HOME is not set}/.claude/skills/localseoskills}"
  22. SKILLS_DIR="${LSS_SKILLS_DIR:-${HOME}/.claude/skills}"
  23. say() {
  24. printf '\033[1;32m>\033[0m %s\n' "$1"
  25. }
  26. fail() {
  27. printf '\033[1;31mx\033[0m %s\n' "$1" >&2
  28. exit 1
  29. }
  30. backup_briefs() {
  31. local src="$1/briefs"
  32. [ -d "$src" ] || return 0
  33. local backup_root="${HOME}/.claude"
  34. mkdir -p "$backup_root"
  35. local ts
  36. ts="$(date +%Y%m%d-%H%M%S)"
  37. local dst="${backup_root}/lss-briefs-backup-${ts}"
  38. # Collision-safe: append a counter if the target already exists. Protects
  39. # against multiple backups inside the same second, which date stamps miss.
  40. local n=1
  41. while [ -e "$dst" ]; do
  42. dst="${backup_root}/lss-briefs-backup-${ts}-${n}"
  43. n=$((n + 1))
  44. done
  45. say "Backing up briefs to $dst"
  46. cp -a "$src" "$dst"
  47. }
  48. install_fresh() {
  49. _LSS_TMP="$(mktemp -d "${TMPDIR:-/tmp}/lss-install.XXXXXX")"
  50. say "Cloning Local SEO Skills"
  51. # core.longpaths=true is a no-op on macOS/Linux but prevents failures on
  52. # Windows if users run this via WSL or git-bash with paths over 260 chars.
  53. git -c core.longpaths=true clone --depth 1 "$REPO_URL" "$_LSS_TMP/localseoskills"
  54. # Re-check inside the critical section so concurrent runs that slipped past
  55. # the lock (shouldn't happen, but defense in depth) don't nest clones.
  56. if [ -e "$INSTALL_DIR" ]; then
  57. fail "$INSTALL_DIR appeared mid-install. Remove it and rerun."
  58. fi
  59. mv "$_LSS_TMP/localseoskills" "$INSTALL_DIR"
  60. }
  61. update_existing() {
  62. say "Existing install detected at $INSTALL_DIR, updating"
  63. # Sanity check: the existing checkout's origin must actually be this repo.
  64. # Without this, a misconfigured LSS_INSTALL_DIR pointing at an unrelated
  65. # git checkout would get `git reset --hard` against the WRONG origin's
  66. # branch, silently destroying the user's work.
  67. local origin_url
  68. origin_url="$(git -C "$INSTALL_DIR" remote get-url origin 2>/dev/null || echo '')"
  69. case "$origin_url" in
  70. "$REPO_URL"|"${REPO_URL%.git}"|"${REPO_URL%.git}.git"|\
  71. git@github.com:garrettjsmith/localseoskills|\
  72. git@github.com:garrettjsmith/localseoskills.git|\
  73. ssh://git@github.com/garrettjsmith/localseoskills|\
  74. ssh://git@github.com/garrettjsmith/localseoskills.git)
  75. ;;
  76. *)
  77. 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." ;;
  78. esac
  79. # Refuse to clobber uncommitted local changes inside the install dir. Covers
  80. # tracked-modified (diff), staged (diff --cached), AND untracked files that
  81. # are not gitignored. Without the untracked check, a user's personal note or
  82. # experimental file dropped into the install dir would be silently wiped by
  83. # `git reset --hard`. The `--exclude-standard` flag respects .gitignore, so
  84. # briefs/<client>/ (gitignored) and .env remain invisible to this check.
  85. if ! git -C "$INSTALL_DIR" diff --quiet \
  86. || ! git -C "$INSTALL_DIR" diff --cached --quiet \
  87. || [ -n "$(git -C "$INSTALL_DIR" ls-files --others --exclude-standard 2>/dev/null)" ]; then
  88. 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)."
  89. fi
  90. # Refuse to switch branches silently on a detached HEAD.
  91. local branch
  92. if ! branch="$(git -C "$INSTALL_DIR" symbolic-ref --short HEAD 2>/dev/null)"; then
  93. fail "Refusing to update: $INSTALL_DIR is on a detached HEAD. Check out a branch first, or remove $INSTALL_DIR and rerun."
  94. fi
  95. backup_briefs "$INSTALL_DIR"
  96. if ! git -C "$INSTALL_DIR" fetch --depth 1 origin "$branch"; then
  97. fail "git fetch failed. Check your network connection and try again."
  98. fi
  99. if ! git -C "$INSTALL_DIR" reset --hard "origin/$branch"; then
  100. fail "git reset failed. Remove $INSTALL_DIR manually and rerun."
  101. fi
  102. }
  103. # Claude Code only discovers <skills dir>/<name>/SKILL.md, one level deep, so
  104. # link each skill folder out of the clone. Never replaces something that isn't
  105. # already a link into this clone (a user's own skill with the same name wins).
  106. link_skills() {
  107. mkdir -p "$SKILLS_DIR"
  108. local dir name target linked=0
  109. # Drop links to skills that no longer exist in the clone (removed upstream).
  110. for target in "$SKILLS_DIR"/*; do
  111. if [ -L "$target" ] && [[ "$(readlink "$target")" == "$INSTALL_DIR/skills/"* ]] && [ ! -e "$target" ]; then
  112. rm "$target"
  113. fi
  114. done
  115. for dir in "$INSTALL_DIR"/skills/*/; do
  116. [ -f "${dir}SKILL.md" ] || continue
  117. name="$(basename "$dir")"
  118. target="$SKILLS_DIR/$name"
  119. if [ -L "$target" ] && [[ "$(readlink "$target")" == "$INSTALL_DIR/skills/"* ]]; then
  120. rm "$target"
  121. elif [ -e "$target" ] || [ -L "$target" ]; then
  122. say "Skipping $name: $target already exists and is not from this install."
  123. continue
  124. fi
  125. ln -s "${dir%/}" "$target"
  126. linked=$((linked + 1))
  127. done
  128. say "Linked $linked skills into $SKILLS_DIR"
  129. }
  130. configure_mcp() {
  131. # The server signs people in with OAuth in the browser on first use, so no
  132. # API key is asked for or written to any config file.
  133. local mcp_url="https://mcp.localseodata.com/mcp"
  134. if command -v claude >/dev/null 2>&1; then
  135. # Earlier installers baked an API key into the URL (?key=), stored in
  136. # plain text in ~/.claude.json. Swap it for the sign-in URL.
  137. local existing=""
  138. existing="$(claude mcp get localseodata 2>/dev/null)" || existing=""
  139. if printf '%s' "$existing" | grep 'key=' >/dev/null; then
  140. local scope
  141. for scope in local project user; do
  142. claude mcp remove localseodata --scope "$scope" >/dev/null 2>&1 || true
  143. done
  144. if claude mcp get localseodata >/dev/null 2>&1; then
  145. say "Couldn't remove your old LocalSEOData entry, which has an API key in its URL. Run: claude mcp remove localseodata"
  146. say "Then revoke that key at localseodata.com/dashboard/keys and rerun this script."
  147. return 0
  148. fi
  149. say "Replaced your old key-based LocalSEOData connection with browser sign-in. You can revoke that key at localseodata.com/dashboard/keys."
  150. existing=""
  151. fi
  152. if [ -n "$existing" ]; then
  153. say "LocalSEOData already configured in Claude Code, skipping."
  154. return 0
  155. elif claude mcp add --transport http --scope user localseodata "$mcp_url" 2>/dev/null; then
  156. say "LocalSEOData added to Claude Code (all projects). You'll sign in the first time a tool runs."
  157. return 0
  158. fi
  159. fi
  160. say "To connect LocalSEOData, add this MCP server in your agent (Claude Desktop: Settings > Connectors > Add custom connector):"
  161. printf '\n %s\n\n' "$mcp_url"
  162. }
  163. _LSS_TMP=""
  164. _LSS_LOCK=""
  165. _LSS_LOCK_OWNED=0
  166. cleanup() {
  167. [ -n "$_LSS_TMP" ] && [ -d "$_LSS_TMP" ] && rm -rf "$_LSS_TMP"
  168. # Only remove the lock if THIS process created it. Prevents a failing run
  169. # from deleting a lock that belongs to a concurrent winner.
  170. [ "$_LSS_LOCK_OWNED" -eq 1 ] && [ -n "$_LSS_LOCK" ] && [ -d "$_LSS_LOCK" ] && rmdir "$_LSS_LOCK" 2>/dev/null
  171. return 0
  172. }
  173. main() {
  174. command -v git >/dev/null 2>&1 || fail "git is required but not found. Install git and try again."
  175. # The plugin already provides the skills and the data server; linking them
  176. # here too would show every skill twice. (Claude Code keeps one copy of the
  177. # data server, so only the skills would repeat.)
  178. 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
  179. say "The Local SEO Skills plugin is installed, which already provides the skills and LocalSEOData. Nothing to do."
  180. say "To use this script instead, uninstall the plugin first (/plugin in Claude Code)."
  181. say "If you ran this script before installing the plugin, run uninstall.sh to remove its copies, or each skill shows up twice."
  182. exit 0
  183. fi
  184. # Pre-install path guard. Install is not destructive like uninstall, but
  185. # an admin running `install.sh` with LSS_INSTALL_DIR pointing at a system
  186. # root would create a skills directory there. Port the core refusals from
  187. # uninstall.sh so this class of mistake fails before we mkdir anything.
  188. case "/$INSTALL_DIR/" in
  189. */../*) fail "Refusing to install to path with .. traversal: $INSTALL_DIR" ;;
  190. esac
  191. if [ -L "$INSTALL_DIR" ]; then
  192. fail "Refusing to install into a symlink: $INSTALL_DIR"
  193. fi
  194. # Minimal blocklist (top-level only; install creates, not destroys, so the
  195. # full prefix+case+symlink apparatus from uninstall is overkill here). The
  196. # PS side has the same guard via Test-SafeInstallPath.
  197. case "${INSTALL_DIR%/}" in
  198. /|""|\
  199. /root|/home|/Users|\
  200. /usr|/etc|/var|/tmp|/bin|/sbin|/opt|/boot|/dev|/proc|/sys|/lib|/mnt|/srv|\
  201. /run|/media|/lost+found|/snap|/selinux|/sysroot|\
  202. /Library|/System|/Applications|/private|/cores|/Volumes|/Network|/.vol)
  203. fail "Refusing to install to system path: $INSTALL_DIR" ;;
  204. esac
  205. # Pre-flight writability check so custom LSS_INSTALL_DIR pointing somewhere
  206. # the user can't write (e.g. /opt/... without sudo) fails with a clear
  207. # message instead of a cryptic git or mv error later.
  208. local parent
  209. parent="$(dirname "$INSTALL_DIR")"
  210. if ! mkdir -p "$parent" 2>/dev/null; then
  211. fail "Cannot create $parent. Check permissions or set LSS_INSTALL_DIR to a user-writable path."
  212. fi
  213. if [ ! -w "$parent" ]; then
  214. fail "$parent is not writable by this user. Set LSS_INSTALL_DIR to a user-writable path, or rerun with appropriate permissions."
  215. fi
  216. # Serialize concurrent installs into the same dir. mkdir is atomic on POSIX,
  217. # so whichever process creates the lock dir first wins; the other aborts
  218. # cleanly instead of racing and nesting clones. Set trap BEFORE mkdir, and
  219. # only mark the lock as owned after mkdir succeeds, so a failing losing
  220. # process never removes the winner's lock.
  221. trap cleanup EXIT
  222. local lock_candidate="${INSTALL_DIR}.lock"
  223. if ! mkdir "$lock_candidate" 2>/dev/null; then
  224. fail "Another install is in progress (lock at $lock_candidate). If stale, remove it and retry."
  225. fi
  226. _LSS_LOCK="$lock_candidate"
  227. _LSS_LOCK_OWNED=1
  228. if [ -d "$INSTALL_DIR/.git" ] && git -C "$INSTALL_DIR" rev-parse --git-dir >/dev/null 2>&1; then
  229. update_existing
  230. elif [ -e "$INSTALL_DIR" ]; then
  231. fail "$INSTALL_DIR exists and is not a clean git checkout. Remove it and rerun."
  232. else
  233. install_fresh
  234. fi
  235. link_skills
  236. say "Local SEO Skills installed."
  237. configure_mcp
  238. cat <<'EOF'
  239. Next steps:
  240. 1. Open Claude Code or your preferred AI agent.
  241. 2. Mention any local business to get started. For example:
  242. "Audit Mike's Plumbing in Buffalo"
  243. The agent will ask 5 questions, run an audit, and set up a persistent
  244. brief for ongoing work.
  245. Docs: https://github.com/garrettjsmith/localseoskills
  246. Community: https://discord.gg/dBtF26Ga2a
  247. EOF
  248. }
  249. main "$@"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.