compare-repos

name	compare-repos
description	Use when an agent needs to compare public GitHub repositories, shortlist OSS projects, or produce provenance-backed repo reports with the keyless CLI, typed schema, HTML dashboard, and ChatGPT App bridge. NOT for private repo audits, paid-source research, or changing repositories.
argument-hint	<mode> [repo-or-url...]
model	opus
license	MIT
compatibility	Requires uv, Python 3.12+, optional Node.js/pnpm for docs UI, optional GITHUB_TOKEN for GitHub GraphQL fallback.
metadata	{"author":"wyattowalsh","version":"1.0.0"}

Compare Repos

Use this skill to run compare-repos safely and interpret its reports.

Dispatch

$ARGUMENTS	Action
Empty	Show quick start, accepted inputs, and keyless policy
doctor	Run uv run compare-repos doctor --json and report setup state
resolve <repo-or-url...>	Normalize flexible repo inputs before comparing
compare <repo-or-url...>	Generate JSON and HTML comparison reports
report <path>	Render or inspect an existing compare-repos.report.v1 file
sources	List keyless and optional data sources
forecast <report-path-or-repo...>	Inspect forecast series, confidence bands, and no-forecast caveats
metrics <report-path>	Explain metric definitions, formulas, score components, and confidence
export <report-path>	Export matrix, metrics, sources, warnings, forecasts, score, health, rationale, or share datasets
explain <metric>	Explain a metric formula, source ids, caveats, and comparability flags
chatgpt	Show Apps SDK/MCP setup notes
install	Show global cross-harness skill install command
audit	Validate CLI, docs, skill, and report surfaces
Natural language comparison request	Resolve inputs, run doctor, then compare

Reference File Index

File	Content	Read When
references/cli-workflow.md	Command order and examples	Running the CLI
references/repo-inputs.md	Accepted input grammar and rejection policy	Parsing user-provided repos
references/data-model.md	Pydantic report and SQLModel cache contract	Inspecting reports or changing schema
references/source-confidence.md	Source ordering, key policy, confidence rules	Explaining report evidence
references/chatgpt-app.md	Apps SDK/MCP bridge setup	ChatGPT app work
references/troubleshooting.md	Common failures and fixes	Debugging errors

Workflow

Default Order

1. Run uv run compare-repos doctor --json.
2. Resolve inputs with uv run compare-repos resolve ... --json.
3. Compare with uv run compare-repos compare ... --out reports/<name> --format json,html.
4. Inspect warnings, source confidence, and provenance before summarizing.
5. Use uv run compare-repos render --input <report.json> --out <report.html> for re-rendering.
6. Use uv run compare-repos export --input <report.json> --dataset all --format csv --out exports/<name> for canonical export handoffs.
7. Use uv run compare-repos share --input <report.json> --variant all --out exports/<name>-share --text --json for comparative social-share SVGs and copy.
8. Use compare --format all, compare --format all-csv, or compare --format share-svg when a fresh run should emit those artifacts directly.
9. For a single repository, treat the report as a repository dossier: summarize repository_insights, strengths, watch items, next checks, source ids, and confidence before discussing ranking-style fields.

Evidence Handling

Report conclusions only after checking warnings, sources, and metric-level confidence. When a metric is single-source, stale, degraded, or package-derived, state that caveat next to the claim instead of burying it at the end.

Scaling Strategy

Repo Count	Strategy
1-2	Inline compare and summarize source caveats
3-10	Compare normally; use report UI filters for analysis
11-50	Prefer repo file input, expect partial source warnings, summarize by metric groups
51+	Ask to split into cohorts; v1 is optimized for up to 50 repos per run

State Management

• Use the CLI output directory as the run state boundary: reports/<name>.json is the canonical report and reports/<name>.html is the portable view.
• Treat local SQLite cache entries as disposable acceleration, not source of truth. Use compare-repos cache status --json before diagnosing cache issues.
• Keep summaries tied to one generated report path and schema version. Do not merge metrics from multiple runs unless the user explicitly asks for a trend.

Progressive Disclosure

• Start with a concise comparison summary: repos, profile, top deltas, major warnings, and report paths.
• Expand into metric groups only when the user asks or when a warning materially changes interpretation.
• Use provenance drawers, source records, and raw payload refs for audit detail; keep normal answers focused on decision-relevant evidence.

Critical Rules

1. Preserve keyless mode as the default.
2. Do not require GITHUB_TOKEN; use it only when present.
3. Normalize repo inputs before querying sources.
4. Never hide source warnings or confidence caveats in summaries.
5. Do not compare package-download counts across ecosystems as a universal score.
6. Treat compare-repos.report.v1 as the public report contract.
7. Forecasts must include confidence and caveats, or explicit no-forecast reasons.
8. Run validation before declaring skill or CLI work complete.

Canonical Vocabulary

Use these terms exactly:

• keyless mode: no API keys required.
• github-token-enhanced mode: optional GITHUB_TOKEN is present.
• source record: provider, endpoint, access time, cache state, conditional-cache state, and parser data.
• metric observation: normalized metric plus confidence and provenance.
• source health: provider-level summary of source counts, warning state, and cache state.
• decision rationale: ranked explanation of profile score drivers with source ids.
• UI projection: precomputed report fields used by the HTML dashboard.

Validation

uv run compare-repos doctor --json
uv run compare-repos resolve facebook/react https://github.com/vuejs/core --json
uv run ruff check
uv run ruff format --check
uv run ty check
uv run pytest

Skill package proof commands:

uv run --directory <agents-repo> wagents validate
uv run --directory <agents-repo> wagents eval validate
uv run --directory <agents-repo> python skills/skill-creator/scripts/audit.py <skill-path> --format table --strict
uv run --directory <agents-repo> wagents package <skill-path> --dry-run --format json