Skip to content
Back to search

geoptimize

SkillGitHubIncomplete

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/cucuwang--geoptimize/badge.svg)](/listings/cucuwang--geoptimize)

HTML

<a href="/listings/cucuwang--geoptimize"><img src="/api/listings/cucuwang--geoptimize/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js 22.12 or newer.

npm install --save-dev geoptimize
npx geoptimize scan https://example.com
npx geoptimize scan ./dist --dir
npx geoptimize scan ./dist --dir --json
npx geoptimize audit https://example.com --json
npx geoptimize audit-site https://example.com --max-pages 20 --json

Version 0.12.0 includes a guided terminal menu for scanning a target and saving an offline HTML report. See [the interactive CLI guide](docs/interactive-cli.md) for `npm install` and `npx` usage; explicit commands remain available for scripts and non-TTY environments.

Example output:

Content Readiness Report
Score: 71/100

Structure        20/25
Citability       18/25
Schema           16/20
AI Metadata      10/15
Content Density   7/15

The score is a versioned heuristic for catching regressions within the same project. Do not treat it as a percentage chance of search or AI visibility, and do not compare unrelated sites as if it were an outcome metric.

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 · 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "geoptimize",
  3. "owner": {
  4. "name": "Te-Shu Wang"
  5. },
  6. "metadata": {
  7. "description": "Content quality lint for CI and pre-commit in documentation and static sites, with optional SEO experiments",
  8. "version": "0.12.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "geoptimize",
  13. "source": "./",
  14. "description": "CLI and skills for content quality lint in documentation and static-site workflows, with optional SEO experiments",
  15. "category": "seo",
  16. "tags": ["geo", "seo", "ai-search", "llms-txt", "structured-data"],
  17. "homepage": "https://github.com/cucuwang/geoptimize",
  18. "repository": "https://github.com/cucuwang/geoptimize"
  19. }
  20. ]
  21. }
README.md · README · 404 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # geoptimize
  2. [English](README.md) | [繁體中文](docs/readme/README.zh-TW.md) | [简体中文](docs/readme/README.zh-CN.md) | [日本語](docs/readme/README.ja.md) | [한국어](docs/readme/README.ko.md) | [Español](docs/readme/README.es.md) | [Français](docs/readme/README.fr.md) | [Deutsch](docs/readme/README.de.md) | [Português do Brasil](docs/readme/README.pt-BR.md)
  3. **Formerly aeoptimize.** This is the same project, continued under the `geoptimize` name from version 0.8.0. Existing `aeoptimize` users can follow the [migration guide](https://github.com/cucuwang/geoptimize/blob/main/docs/migrating-from-aeoptimize.md).
  4. [Current npm package](https://www.npmjs.com/package/geoptimize) · [Legacy npm package and download history](https://www.npmjs.com/package/aeoptimize) · [Last release under the old name](https://github.com/cucuwang/geoptimize/releases/tag/v0.7.0)
  5. [![npm version](https://img.shields.io/npm/v/geoptimize.svg)](https://www.npmjs.com/package/geoptimize)
  6. [![CI](https://github.com/cucuwang/geoptimize/actions/workflows/ci.yml/badge.svg)](https://github.com/cucuwang/geoptimize/actions/workflows/ci.yml)
  7. [![license](https://img.shields.io/npm/l/geoptimize.svg)](https://github.com/cucuwang/geoptimize/blob/main/LICENSE)
  8. **Content quality lint for CI. Catch regressions before you publish.**
  9. `geoptimize` runs content lint in CI or pre-commit to catch regressions in documentation and static sites before publication. Its deterministic checks flag document-structure issues, source signals missing from quantitative claims, metadata problems, JSON-LD structural issues, indexing controls such as noindex and canonical, and repetitive wording. Review findings in pull requests, audit built HTML, and choose a project-specific threshold when you are ready to block regressions.
  10. https://github.com/user-attachments/assets/5dafd888-92c9-428b-b372-62864c58059a
  11. 30-second introduction · [Download the MP4](https://github.com/cucuwang/geoptimize/raw/refs/heads/main/marketing/geoptimize-preview-20260916/output/geoptimize-preview-v2.mp4) · [Video source and credits](https://github.com/cucuwang/geoptimize/tree/main/marketing/geoptimize-preview-20260916)
  12. [![geoptimize visual report with five readiness scores and site health charts](docs/assets/report-demo.png)](docs/assets/report-demo.html)
  13. [Open the offline example](docs/assets/report-demo.html) · [After improvements](docs/assets/report-demo-after.html)
  14. ![geoptimize terminal demo](docs/assets/demo.gif)
  15. ## Who it is for
  16. - Documentation teams that want repeatable content checks in pull requests.
  17. - Frontend engineers and maintainers of static or documentation sites built with Astro, Docusaurus, VitePress, MkDocs, or similar tools that output HTML.
  18. - Teams that want CI to flag content regressions and block changes below an accepted project baseline.
  19. After your workflow builds the site into `dist`, add this GitHub Actions step. Review the baseline before enabling blocking mode; `60` is an example threshold, not a universal quality target.
  20. ```yaml
  21. - uses: cucuwang/geoptimize@v0.12.0
  22. with:
  23. path: dist
  24. fail-on-low-score: 'true'
  25. min-score: '60'
  26. ```
  27. The Action is advisory by default. See the [CI contract](#ci-contract) for outputs and reproducibility details.
  28. It does **not** predict ranking, indexing, rich results, Google AI Overviews, or citation by ChatGPT, Perplexity, or another AI system. Google states that its AI search features need no special AI text file or schema, and valid structured data does not guarantee a search feature. See [methodology and limitations](docs/methodology.md).
  29. ## Quick start
  30. Requires Node.js 22.12 or newer.
  31. ```bash
  32. npm install --save-dev geoptimize
  33. ```
  34. ```bash
  35. npx geoptimize scan https://example.com
  36. npx geoptimize scan ./dist --dir
  37. npx geoptimize scan ./dist --dir --json
  38. npx geoptimize scan ./dist --dir --fail-under 60 --json
  39. npx geoptimize audit https://example.com --json
  40. npx geoptimize audit-site https://example.com --max-pages 20 --json
  41. ```
  42. Version 0.12.0 includes a guided terminal menu for scanning a target and saving an offline HTML report. See [the interactive CLI guide](docs/interactive-cli.md) for `npm install` and `npx` usage; explicit commands remain available for scripts and non-TTY environments.
  43. Example output:
  44. ```text
  45. Content Readiness Report
  46. Score: 71/100
  47. Structure 20/25
  48. Citability 18/25
  49. Schema 16/20
  50. AI Metadata 10/15
  51. Content Density 7/15
  52. ```
  53. The score is a versioned heuristic for catching regressions within the same project. Do not treat it as a percentage chance of search or AI visibility, and do not compare unrelated sites as if it were an outcome metric.
  54. ## What is scored
  55. | Dimension | Max | Scope |
  56. | --- | ---: | --- |
  57. | Structure | 25 | Document outline and readability heuristics |
  58. | Citability | 25 | Claim specificity, source signals, definitions, attribution |
  59. | Schema | 20 | JSON-LD structural hygiene when present; absence is not penalized |
  60. | AI Metadata | 15 | Page-level indexing control and description quality |
  61. | Content Density | 15 | Content/boilerplate and repetition heuristics |
  62. Two often-promoted GEO signals are deliberately excluded from the score:
  63. - FAQ content and `FAQPage` schema are optional. The generator does not infer FAQ schema from question headings.
  64. - `llms.txt` is an experimental proposal. Generating or publishing it does not add points.
  65. Every rule, its evidence class, and known false-positive boundary is documented in [docs/methodology.md](docs/methodology.md) and exercised by the [versioned public fixture corpus](fixtures/v0.6/rule-corpus.ts).
  66. [Follow the CI content quality tutorial](docs/tutorials/ci-content-quality.md) for a two-page static site, JSON output, build audit failures, and an optional Action threshold.
  67. ## Evidence-backed page audit
  68. `audit` inspects one public URL or one local HTML/Markdown file. It is a separate, versioned contract and does not change the v0.6 readiness score or `scan --json` output.
  69. ```bash
  70. npx geoptimize audit https://example.com
  71. npx geoptimize audit ./dist/index.html --json
  72. ```
  73. The first audit contract checks:
  74. - HTTP status, final URL, and redirect evidence for URL targets;
  75. - document title, meta description, headings, language, canonical, and page-level robots directives;
  76. - discovered links, image alt attributes, and JSON-LD structural validity.
  77. Each check returns `PASS`, `WARNING`, `FAIL`, or `N/A`, the observed evidence, an explanation, an optional remediation, and a validation step. `PASS` is bounded to the inspected evidence. It does not establish ranking, indexing, rich-result display, traffic, conversion, or AI citation.
  78. The command intentionally reports unavailable site-wide and external measurements as limitations. It does not infer robots.txt policy, sitemap membership, hreflang reciprocity, broken-link status, Core Web Vitals, analytics, or actual search-engine index state from one page.
  79. ## Bounded site audit
  80. `audit-site` follows same-origin links in deterministic order and stops at an explicit page limit. It reads robots.txt before subsequent page requests, discovers same-origin sitemap files, and uses response HTML without browser rendering.
  81. ```bash
  82. npx geoptimize audit-site https://example.com
  83. npx geoptimize audit-site https://example.com --max-pages 50 --json
  84. ```
  85. The site contract reports bounded crawl coverage, robots policy, page status, redirect chains, internal link targets, canonical consistency, sitemap discrepancies, sitemap-only orphan candidates, and duplicate titles. Sitemap-only pages remain candidates until a sufficiently complete crawl or server-log evidence confirms their discovery state.
  86. The default limit is 20 page requests and the accepted range is 1–200. Cross-origin page links are recorded only as counts, and subsequent redirects outside the audited origin are not followed. JavaScript-inserted links, actual search-engine crawl/index state, rankings, traffic, and conversions remain outside this contract.
  87. ## Visual report
  88. Keep the original total and all five readiness dimensions together with page-score
  89. and severity charts. Add site-audit data for HTTP charts, canonical/link/sitemap
  90. observations, and baseline comparisons. Search individual pages or expand findings
  91. to inspect evidence and suggested actions.
  92. ```bash
  93. geo scan ./dist --dir --details --json > readiness.json
  94. geo audit-site https://example.com --max-pages 50 --json > site.json
  95. geo report readiness.json --site site.json --output report.html
  96. # Add --baseline previous-readiness.json for score and source comparisons.
  97. # Add --baseline-site previous-site.json for comparable site-count charts.
  98. ```
  99. Detailed scans include original rule results and a source excerpt of up to 6000
  100. characters per page. Review captured source before sharing. Reports without details
  101. still open, with unavailable rule/source evidence labeled explicitly.
  102. Click score distributions to filter pages, or a severity label to inspect those
  103. scoring findings. Site finding controls expose the complete affected target list.
  104. Open a dimension to inspect rule points and diagnostics. A compatible readiness
  105. baseline adds total/dimension changes and captured before/after source excerpts.
  106. Open the resulting HTML in a browser. It works offline with no external fonts,
  107. scripts, or analytics. Existing output files are preserved; choose a new filename
  108. for another report. The scoring algorithm is unchanged. Readiness and site audit
  109. scope/timestamps remain visible because the two inputs can cover different pages.
  110. The example reports use the same synthetic HTML for readiness and site audits.
  111. In a repository checkout, generate them with `node scripts/prepare-metrics-demo.mjs <empty-directory>` after
  112. building. Browser checks run with `node scripts/verify-visual-report.mjs <directory>`;
  113. set `GEO_CHROME` to a Chrome executable on platforms outside macOS.
  114. ## Site metrics and scan comparisons
  115. Summarize the site audit into 19 observed counts, including HTTP failures, redirects,
  116. internal link targets, canonical findings, sitemap discrepancies and duplicate titles.
  117. Save each scan to a new JSON file to retain its timestamp and evidence.
  118. ```bash
  119. geo audit-site https://example.com --max-pages 50 --json > before.json
  120. # After updating the site, scan the same URL with the same limit.
  121. geo audit-site https://example.com --max-pages 50 --json > after.json
  122. geo metrics after.json --baseline before.json
  123. geo metrics after.json --baseline before.json --json
  124. ```
  125. The comparison lists count differences and new, persisting, and no-longer-observed
  126. findings. An absent observation needs evidence review before calling it a repair.
  127. Changes in origin, start URL, page limit, crawled URL set, or metric evidence version
  128. suppress deltas. Partial crawls, robots skips, unavailable requests, and a newer
  129. baseline also suppress comparison. Absolute counts remain available.
  130. Counts use complete evidence, even when the detailed audit displays only 20 sample
  131. URLs. Older reports without complete counts display `Not measured`. Queue completion
  132. is bounded discovery, so no whole-site coverage percentage is inferred. AI mentions,
  133. citations, traffic and conversions require separate collection and remain unmeasured.
  134. The terminal demo uses a synthetic three-page fixture with actual audit output.
  135. To reproduce it after building, run `vhs docs/assets/demo.tape`. The preparation script
  136. also accepts an empty output directory for inspecting readiness and site JSON reports plus the interactive HTML examples without VHS.
  137. ## How it compares
  138. | | geoptimize | Lighthouse-style SEO audits | Hosted GEO platforms |
  139. | --- | --- | --- | --- |
  140. | Question it answers | Did this change introduce content-quality issues? | Does the page pass classic SEO checks? | Did my AI visibility change this week? |
  141. | Deterministic | Yes — versioned rules, fixture-tested | Partially | No — model output varies run to run |
  142. | Runs where | Local CLI, CI, pre-commit hook, Vite/Next plugins | Browser / DevTools | Vendor cloud |
  143. | Blocks regressions in CI | Yes, with `scan --fail-under` and `audit-build --fail-on-error` | Possible with extra wiring | Rarely |
  144. | Cost | Free, MIT | Free | Varies by vendor |
  145. geoptimize gives teams reproducible content checks they can act on in a pull request. Visibility trackers provide separate measurements of search and AI visibility outcomes.
  146. ## CI contract
  147. `--json` is the stable automation surface. A non-zero threshold is useful only after your team reviews the baseline and accepts the current methodology version.
  148. ```bash
  149. npx geoptimize scan ./dist --dir --fail-under 60 --json > geoptimize-report.json
  150. ```
  151. `scan` remains advisory by default. Add `--fail-under <score>` to exit `1` when
  152. the deterministic overall score is strictly below the selected threshold. Scores
  153. equal to or above the threshold exit `0`. The threshold accepts finite numbers
  154. from 0 to 100, including decimals. For directories it applies to the overall
  155. average, rather than each page. With `--multi-ai`, it uses the deterministic
  156. `ruleScore`, even when the experimental blend is higher.
  157. The complete report is written to stdout before a threshold failure; its explanation
  158. is written to stderr, so redirected `--json` stays valid JSON. Invalid options,
  159. unreadable inputs and scan execution errors exit `1`. A completed scan without
  160. `--fail-under` exits `0`, including an empty directory (reported with score 0).
  161. JSON-LD findings include the file or URL and the one-based source line of the
  162. script's opening tag. The existing readiness point calculations are preserved;
  163. syntax and field-type diagnostics add findings without additional point deductions.
  164. Use `audit-build ./dist --fail-on-error` alongside a score threshold to block
  165. malformed JSON-LD and invalid root shapes independently of the score.
  166. The [GitHub Marketplace Action](https://github.com/marketplace/actions/geoptimize-content-readiness-check) is advisory by default. It reports findings without blocking the workflow:
  167. ```yaml
  168. - uses: cucuwang/geoptimize@v0.12.0
  169. with:
  170. path: dist
  171. ```
  172. Projects can explicitly choose blocking mode after accepting a baseline:
  173. ```yaml
  174. - uses: cucuwang/geoptimize@v0.12.0
  175. with:
  176. path: dist
  177. fail-on-low-score: 'true'
  178. min-score: '60'
  179. ```
  180. The Action exposes `score` and `report` outputs in both modes. Its default selects an exact npm package version; transitive dependencies are resolved at install time. Verify the Action tag and matching npm package before pinning. See the [Action reproducibility decision](docs/action-reproducibility.md) for the remaining dependency-resolution boundary.
  181. A copyable advisory workflow and controlled input are available in the [end-to-end Action sample](examples/github-action-sample/README.md).
  182. ## Audit built HTML before deployment
  183. The `audit-build` command checks a local HTML file or build directory and reports evidence,
  184. remediation and validation for each finding. It leaves the existing `scan` score and
  185. JSON contract unchanged.
  186. ```bash
  187. npx geoptimize audit-build ./dist --json
  188. npx geoptimize audit-build ./dist --base-url https://example.com/ --expect-indexable --fail-on-error --json > audit.json
  189. ```
  190. Malformed JSON-LD, invalid root shapes, and invalid or multiple canonical declarations
  191. produce `FAIL`. Missing entity `@context`/`@type` and other structural diagnostics
  192. produce `WARNING`. JSON-LD evidence identifies
  193. the page, script start line, block number and object/graph path. Graph entities can
  194. inherit their envelope's context; an envelope containing only graph metadata needs
  195. no entity type. A type can be a string or a non-empty array of strings.
  196. HTML `noindex` and `none` are warnings unless `--expect-indexable` is supplied.
  197. Missing or repeated titles/descriptions and cross-page title/canonical reuse are
  198. advisory. Shared canonicals can be intentional; they are never automatically rewritten.
  199. `--fail-on-error` exits with code 1 when a `FAIL` is present, while still writing the
  200. complete report. Input errors also exit 1. Without it, a completed audit is advisory.
  201. Use `--expect-indexable` only for pages intended for standalone search indexing.
  202. This command reads source HTML without fetching URLs or launching a browser.
  203. HTTP headers, robots.txt and actual indexing are explicitly unassessed. JSON-LD
  204. checks cover JSON syntax, root shape, context shape and entity types; schema semantics and visible-content
  205. consistency require separate validation. Missing JSON-LD is `N/A`.
  206. For a file, `--base-url` is its deployed page URL. For a directory, it is the
  207. deployment root; relative file paths are appended without inferring hosting rewrites.
  208. An HTML `base` element is respected. Relative canonicals without a resolvable base
  209. are `N/A`. Hidden entries, `node_modules` and symlinks are excluded from traversal;
  210. an explicit symlink input is rejected. Unreadable files and files over 5 MB stop
  211. the audit instead of silently dropping pages.
  212. Rules follow the [robots meta specification](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag)
  213. and [canonical URL guidance](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls).
  214. A syntax pass does not establish eligibility under the
  215. [structured-data policies](https://developers.google.com/search/docs/appearance/structured-data/sd-policies).
  216. ## Secondary use: GEO and AI search
  217. Teams working on GEO or AI search can use the same checks to review content structure, source signals, and discovery controls. Search and AI visibility outcomes require separate measurement.
  218. For measured Google Search experiments, initialize the separate SEO ledger:
  219. ```bash
  220. geo seo init .
  221. geo seo add . --keyword "energy management system integration" --page /services/ems/ --priority high
  222. geo seo status .
  223. ```
  224. The ledger allows one monitoring experiment at a time and preserves fixed query, page, country, device, search type, and date-window evidence. Start its seven-day review period only after the changed page is publicly deployed and read back. The ledger does not affect the readiness score. See [SEO experiment ledger](docs/seo-experiment-ledger.md).
  225. ## Optional generators
  226. ```bash
  227. npx geoptimize generate ./dist --dry-run
  228. npx geoptimize generate ./dist
  229. ```
  230. The generator can create:
  231. - `llms.txt` and `llms-full.txt` as experimental outputs based on the [llms.txt proposal](https://llmstxt.org/);
  232. - candidate `Article` and `BreadcrumbList` JSON-LD for manual review;
  233. - crawler-specific `robots.txt` suggestions, printed but never applied automatically.
  234. Generated structured data must be reviewed against visible content and the applicable search-engine documentation. The generator intentionally does not create `FAQPage` from headings alone.
  235. ## Framework integrations
  236. ### Vite
  237. ```ts
  238. import { defineConfig } from 'vite';
  239. import { geoPlugin } from 'geoptimize/vite';
  240. export default defineConfig({
  241. plugins: [geoPlugin()],
  242. });
  243. ```
  244. ### Next.js
  245. ```js
  246. import { withGeo } from 'geoptimize/next';
  247. export default withGeo({});
  248. ```
  249. Both integrations scan the build output and generate the same optional artifacts as the CLI. Options: `{ silent?: boolean; outDir?: string }`.
  250. ## Experimental AI review
  251. ```bash
  252. npx geoptimize scan https://example.com --multi-ai
  253. ```
  254. When supported local AI CLIs are available, this adds a subjective review and reports an experimental blend. Model output can vary and is not ground truth. The deterministic rule score remains visible separately.
  255. ## Pre-commit hook
  256. ```bash
  257. npx geoptimize hook install
  258. npx geoptimize hook install --min-score 60
  259. npx geoptimize hook uninstall
  260. ```
  261. The hook checks staged `.html`, `.htm`, `.md`, and `.mdx` content. Review the baseline before using a threshold to block commits; `git commit --no-verify` remains an explicit escape hatch.
  262. ## Claude Code skills
  263. ```bash
  264. claude plugin marketplace add cucuwang/geoptimize
  265. claude plugin install geoptimize@geoptimize
  266. ```
  267. Or install the same reusable skills through the cross-agent Agent Skills CLI (skills.sh indexes installs from this command; there is no separate submit form):
  268. ```bash
  269. npx skills add cucuwang/geoptimize
  270. ```
  271. - `/geo-scan` — deterministic readiness audit with optional experimental review
  272. - `/geo-generate` — preview optional discovery artifacts
  273. - `/geo-transform` — propose content edits without inventing claims
  274. - `/seo-experiment-ledger` — maintain one evidence-bounded search experiment
  275. ## Project status
  276. Version 0.12.0 fixes readiness scoring for JSON-LD graphs, CJK text, and SVG titles, and improves canonical consolidation and hreflang handling in site audits. Scoring is now `readiness-v0.6.1-details-v1`, and metric evidence is `1.1`. Older detailed reports remain readable; previous scoring baselines are non-comparable, and cross-version metric evidence produces no deltas. See the [release notes](https://github.com/cucuwang/geoptimize/releases/tag/v0.12.0), [release runbook](docs/release-v0.12.md), and [roadmap](ROADMAP.md).
  277. Contributions are welcome. Rule changes require an evidence note and positive/negative fixtures; see [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities through the process in [SECURITY.md](SECURITY.md).
  278. ## Release integrity and security maintenance
  279. The v0.12 release path is documented in [the v0.12 runbook](docs/release-v0.12.md). The v0.10 runbook remains the historical record for the verified v0.10.0 release.
  280. CI validates Node 22/24 tarballs, package contents and CLI/Action contracts; the
  281. release preparation exports SHA-256 checksums and an SPDX production-dependency SBOM.
  282. Repository settings and npm authorization remain explicit [maintainer gates](docs/maintainer-security-settings.md).
  283. [OpenSSF Passing preparation](docs/openssf-best-practices.md) records outstanding
  284. verification. Scorecard/Best Practices badges will be added only after real results exist.
  285. ## License
  286. MIT
  287. If geoptimize catches something real in your build, a star helps other teams find it.

Ratings and comments

Sign in to rate this skill.

Sign in

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