Repo findability

Repo & Deployment Findability

Two distinct audiences must be able to find the project:

1. Search engines / end users → crawl and index the deployed site (Vercel/Netlify/Render/Fly).
2. Developers → discover the GitHub repo via topics, search, and a clear README.

This skill covers both. Always audit first (report current state), then fix automatable items, then hand the user the manual high-impact steps (search-console submission, social distribution). Do not silently change GitHub metadata or push commits without confirming with the user.

Inputs to gather first

• Repo: owner/name (derive from git remote -v if not given).
• Live URL: the deployed site URL (check GitHub homepageUrl, the deploy provider, or ask).
• Framework: Next.js, Astro, SvelteKit, Vite SPA, plain static, etc. This decides how sitemap/robots/metadata are added.
• Provider: Vercel | Netlify | Render | Fly. Affects only deploy/config notes, not the SEO files themselves.

Workflow

1. audit() — run scripts/audit.sh <owner/name> <live_url> (or do the checks manually). Report a table of what exists vs. missing. Never assume — verify with gh, file listing, and curl/web_fetch.
2. fix_site_seo() — add/repair the crawlable SEO surface (see "Site SEO" below). Framework-specific. Verify with a build.
3. add_signature() — add a footer attribution signature on every page (see "Footer signature" below). Draft it, show it to the user, and get approval before applying — it is user-visible branding.
4. fix_repo_metadata() — GitHub topics, description (with URL), license, README quality (see "GitHub findability"). Confirm before editing.
5. verify() — rebuild the site; confirm /sitemap.xml and /robots.txt resolve and the sitemap lists every page; confirm the signature renders in the built HTML. Re-query gh repo view to confirm topics/description.
6. handoff() — give the user the manual, high-impact steps that an agent cannot do (Search Console / Bing verification + sitemap submission, social/distribution). See "Manual high-impact steps".

Site SEO (the crawlable surface)

Target three things, in priority order:

1. sitemap.xml — lists every indexable URL. Highest impact: without it, deep pages may never be discovered.
2. robots.txt — allows crawling and points to the sitemap.
3. Metadata — per-page <title> + description, a site-wide metadataBase/canonical, and OpenGraph + Twitter card tags for rich social previews. Optionally a 1200×630 OG image.

Framework recipes

• Next.js (App Router): add app/sitemap.ts and app/robots.ts (use MetadataRoute.Sitemap / MetadataRoute.Robots); set metadata with metadataBase, a title template, openGraph, and twitter in app/layout.tsx; use generateMetadata in dynamic route segments. See references/checklist.md for copy-paste snippets.
• Next.js (Pages Router): use next-sitemap (postbuild) or a custom pages/sitemap.xml.tsx; metadata via next/head or a shared <SEO> component.
• Astro: @astrojs/sitemap integration; public/robots.txt; <meta>/OG tags in the base layout (or astro-seo).
• SvelteKit: a +server.ts route for /sitemap.xml; static/robots.txt; <svelte:head> for meta.
• Vite SPA / plain static: generate a static sitemap.xml + robots.txt into the published output dir (e.g. public/); put OG/meta in index.html. SPAs render poorly for crawlers — prefer SSG/prerender if SEO matters.

Always set the canonical/base URL to the real deployed URL (the provider's domain or the user's custom domain), not localhost.

Provider notes

• Vercel / Netlify: framework adapters serve sitemap.xml/robots.txt automatically once the files/routes above exist; static files in public/ are served at the root. Netlify Next.js builds run via @netlify/plugin-nextjs.
• Render / Fly: same files; ensure the build copies them into the served directory and that no reverse-proxy/route rule blocks /robots.txt or /sitemap.xml.
• Confirm a custom domain choice early; switching domains later forces canonical/sitemap/Search-Console rework.

Footer signature

A small attribution line in the site footer, shown on every page. It credits the author and links back to their portfolio/profile and the repo. This aids findability (an author signal on every page + an internal link to the source) and branding.

Template

Created by {AUTHOR} · {LINK_1_LABEL} ({LINK_1_URL}) · {LINK_2_LABEL} ({LINK_2_URL})

Defaults / how to fill the variables:

• {AUTHOR} — from git config user.name (confirm with the user).
• Links — prefer two: a personal site/portfolio and the repo source. Derive a portfolio/profile URL from gh api user --jq .blog or the GitHub profile (https://github.com/<login>); derive the source URL from the repo. Reasonable default labels: Portfolio (or Site) and Source.
• Wording — default Created by; alternatives the user may pick: Built by, Made by, © {YEAR} {AUTHOR}.
• Year — omit unless the user wants a copyright year.

Example (concrete): Created by Ashutosh Sanzgiri · Portfolio (https://sanzgiri.github.io/portfolio/) · Source (https://github.com/sanzgiri/thinking_tools)

Review the signature (do this before applying)

The signature is user-visible, so always draft it, present it, and get explicit approval. While drafting, validate:

1. Name is spelled correctly and is the form the user wants.
2. Every link resolves (HTTP 200) — check with curl -sI; never ship a dead or placeholder (#) link.
3. No redundancy — if one link (e.g. a portfolio) already contains the others (e.g. a GitHub-profile link), drop the duplicate. Two links is usually the clean maximum.
4. Placement & style — sits in the existing footer, visually subordinate (muted, smaller), does not duplicate other footer content, and matches the site's styling (reuse footer link colors/classes).
5. Wording/year match the user's stated preference.
6. Implementation fits the framework — a footer component/partial, not a hand-edited copy on every page. Add it once where the shared layout/footer lives.

After applying, rebuild and confirm the signature text + both URLs appear in the built HTML.

GitHub findability

• Topics (biggest lever): gh repo edit <owner/name> --add-topic <t> (repeat). Use 5–12 relevant tags: framework (nextjs,astro), language (typescript), domain, and subject keywords people search.
• Description, website field, license, and README polish are covered in "Manual & cross-cutting high-impact items (the 8)" below — see items 1–3.
• Optional: pin the repo on the profile (item 4), add a social preview image in repo settings (related to item 8).

Manual & cross-cutting high-impact items (the 8)

After the automated fixes, walk the user through these. Items 1–3 you can do/draft with confirmation; 4–8 are mostly manual or off-platform — hand them over with exact instructions. Ordered by impact.

1. License — add one if missing (commit a LICENSE file, e.g. MIT). Unlicensed repos deter reuse and stars. Can be automated with confirmation.
2. Repo description + website field — make the description concise and keyword-rich and include/point to the live URL: gh repo edit <owner/name> --description "..." --homepage <url>. Automatable with confirmation.
3. README polish — one-line value prop at the top, a screenshot/GIF, a live-demo link, and the tech stack. Visuals materially increase engagement. Add the screenshot section; the user supplies the image.
4. Pin the repo on the GitHub profile — manual (Profile → Customize your pins). Tell the user; an agent cannot do it.
5. Submit the sitemap to Google Search Console — verify the domain, then submit <url>/sitemap.xml. Single biggest accelerator of indexing. Manual, one-time.
6. Submit the sitemap to Bing Webmaster Tools — verify + submit the sitemap. Manual, one-time.
7. Backlinks / distribution — share where the audience is (relevant subreddits, Hacker News "Show HN", dev.to, communities, link from any related blog/profile). Organic backlinks drive ranking more than on-page tweaks.
8. Custom OG image + analytics — add a 1200×630 OpenGraph image so shared links have rich previews (wire it into the metadata once the user provides/approves an image), and optionally add privacy-friendly analytics (Plausible, Vercel/Netlify Analytics) to measure what works.

Guardrails

• Audit before changing. Report current state with evidence; don't assume files/topics are missing.
• Confirm before mutating GitHub (topics/description/license) or pushing commits. These are user-visible and hard to undo cleanly.
• The footer signature is user-visible — draft, present, and get approval before applying; verify both links resolve and avoid redundant links.
• Verify every change with a build and by fetching /sitemap.xml and /robots.txt, and by confirming the signature renders.
• Use the real deployed URL in canonical/sitemap/robots/signature — never localhost or a placeholder.
• Don't fabricate a live URL; if unknown, ask or derive it from gh repo view --json homepageUrl / the provider.

References

• references/checklist.md — the full audit checklist and copy-paste Next.js snippets (sitemap.ts, robots.ts, layout metadata).
• scripts/audit.sh — prints a findability audit for a repo + live URL.