Uselink Repo Summary

Repo Summary → Uselink

Scan a codebase, generate a clean architecture overview as HTML, and publish it to uselink as a shareable link.

When to Use

• "Summarize this repo and share it"
• "Create an architecture overview for the PM"
• "Share the codebase structure with the new hire"
• User provides a GitHub URL and wants a summary page

Prerequisites

which uselink || echo "MISSING"
test -f ~/.uselink/config.json && echo "OK" || echo "NO_CONFIG"

If either fails, tell the user to install (npm install -g uselink) or configure (uselink login). Do not proceed.

Workflow

1. Get the repo

Local repo (current directory):

git remote get-url origin 2>/dev/null
basename "$(git rev-parse --show-toplevel)"

Remote GitHub URL:

gh repo clone  /tmp/uselink-repo- -- --depth 1
cd /tmp/uselink-repo-

2. Gather data

# Project name and description
gh repo view --json name,description 2>/dev/null

# Languages
gh repo view --json languages 2>/dev/null
find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/build/*" \
  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10

# Directory structure (top 2 levels)
find . -maxdepth 2 -type d -not -path "*/.git*" -not -path "*/node_modules*" -not -path "*/build*" | sort

# Key files
for f in README.md CLAUDE.md package.json build.gradle.kts settings.gradle.kts Cargo.toml go.mod pyproject.toml Makefile docker-compose.yml; do
  test -f "$f" && echo "FOUND: $f"
done

# Git stats
git log --oneline -20
git shortlog -sn --no-merges | head -10
git log -1 --format="%ai"

3. Read key files

Read the first 100 lines of:

• README.md (project description)
• CLAUDE.md (architecture notes, if present)
• Main config file (package.json, build.gradle.kts, etc.)
• Entry point files (scan for main, index, app)

4. Generate HTML

Write to /tmp/uselink-repo-summary--.html.

Use the base HTML template with these sections:

  
    {{TOTAL_FILES}}Files
    {{CONTRIBUTORS}}Contributors
    {{COMMITS}}Commits
    {{LAST_ACTIVITY}}Last active
  

Tech Stack

  LayerTechnology
  

Architecture
{{ASCII_DIAGRAM}}

Directory Structure
{{TREE}}

Key Modules

Getting Started
{{SETUP_COMMANDS}}

Recent Activity

  CommitAuthorDate
  

Use the same inline CSS from uselink-report's base HTML shell (system font, cards, dark mode support).

5. Publish

uselink publish /tmp/uselink-repo-summary--.html \
  --title "Repo Summary -- " \
  --format html

Return the URL to the user.

Gotchas

• NEVER set background or color on body, table, th, td, code, or pre. uselink's viewer injects theme-adaptive CSS that handles light/dark mode automatically. Any hardcoded color in published HTML overrides the viewer's theme and forces a white background in dark mode. Only style layout (padding, margins, borders, border-radius, font-size, grid). Use opacity for muted text instead of color: #888.
• Remote repos need gh CLI. If the user gives a GitHub URL but gh is not installed, fall back to git clone with HTTPS. If that also fails (private repo), tell the user to clone it locally first.
• Don't include secrets or env files in the summary. Skip .env, credentials.json, and similar files when scanning. Never read or display their contents.
• Large repos need sampling. For repos with 1000+ files, show the top-level structure and 3-5 most important modules, not every file. Use find -maxdepth 2 and read only the key files.
• HTML must use inline CSS only. Uselink strips external stylesheets. All styles go in a ` block in `.
• HTML-escape all repo-sourced strings. Commit messages, file paths, and README content can contain `, &` that corrupt the HTML.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: compilet-dev
• Source: compilet-dev/agent-skill-uselink
• License: MIT
• Homepage: https://uselink.app

Install and usage instructions live in the source repository linked above.