history-to-skill 0.3.0

Turn GitHub history into cited repository-maintenance skills for coding agents.

history-to-skill

Turn GitHub history into a cited maintainer skill for your coding agent.

Pull requests, issues, commits, CI, and architecture docs contain the maintenance knowledge a README leaves out. history-to-skill connects that evidence in a repository knowledge graph and gives an Agent Skills-compatible coding agent the material to generate a source-linked operating guide.

The image is a real pallets/flask run: 20 completed changes + 13 documents → 267 nodes, 928 edges, and 3 change communities. See the reproducible Flask example.

Get started in 30 seconds

Install the CLI and register the skill:

uv tool install git+https://github.com/Mandolaro/history-to-skill.git
history-to-skill install --platform codex

Then ask your coding agent:

/history-to-skill pallets/flask

Claude Code and Cursor users can select their own skill directory convention:

history-to-skill install --platform claude
history-to-skill install --platform cursor

Use --project to install inside the current repository, or --force to replace an older installation. With pipx, install directly from the same GitHub URL.

What you get

The read-only collector produces a bounded evidence bundle:

repository history + docs
            │
            ▼
  evidence-graph.json   typed nodes and source-linked edges
  graph-context.md      hotspots, communities, and ranked retrieval views
  corpus.md             bounded and redacted repository evidence
  source-map.md         stable URLs for every citation
  SYNTHESIS.md          contract for the coding agent
            │
            ▼
  <repo>-maintainer/
  ├── SKILL.md
  └── references/
      ├── architecture.md
      ├── conventions.md
      ├── workflows.md
      ├── failure-patterns.md
      └── source-map.md

The generated skill answers practical questions such as:

• Which test, lint, type-check, and release commands does CI actually run?
• Which implementation and test paths repeatedly change together?
• Where are the repository's component boundaries and change hotspots?
• Which fixes or approaches have already failed?
• What evidence supports each repository-specific instruction?

Every claim must cite a repository file, PR, issue, or commit. Graph relationships guide retrieval; they are never presented as proof on their own.

Run the collector directly

You can generate the evidence bundle without installing the Agent Skill:

history-to-skill pallets/flask flask-maintainer --output ./history_skill_work

For an existing checkout:

history-to-skill ~/code/my-service --limit 100 --max-documents 30

Private repositories use GITHUB_TOKEN or GH_TOKEN. Public repositories work without a token, subject to GitHub's unauthenticated rate limit.

Why a graph

A flat search can find a change mentioning a parser regression. The evidence graph can also retrieve the implementation paths, their tests, the component they belong to, and other completed changes that touched the same boundary.

The graph contains inspectable relationships:

• completed PRs and commits change files;
• files belong_to top-level components;
• files changed together receive weighted co_changed edges;
• repeated co-changes form deterministic Louvain communities;
• labels, documents, issues, and repository structure remain linked to their sources.

Graph-aware retrieval combines lexical seeds with personalized PageRank. NetworkX models the graph, SciPy performs sparse ranking, and broad changes are excluded from pairwise co-change expansion to avoid noisy, quadratic edge growth.

Designed for inspectability

Guarantee	Behavior
Read only	Remote repositories are queried through the GitHub API; their code is never executed.
Bounded	History items, documents, and text sizes have explicit limits.
Source linked	Claims resolve to stable file, PR, issue, or commit identifiers.
Injection resistant	Repository text is quarantined as untrusted evidence.
Honest graph semantics	Co-change and PageRank results are retrieval leads, not dependency claims.
Reproducible	Graph construction, Louvain communities, and ranking are deterministic.

See the architecture, evidence format, live benchmarks, and research notes.

Scope

This is a change-history graph, not a symbol-level call graph, vulnerability scanner, or replacement for reading current implementation code. It extracts maintenance knowledge evidenced by repository history and documentation. Vague squash commits, private review conversations, and undocumented release procedures necessarily provide weaker evidence.

Development

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
ruff format --check .
ruff check .
mypy history_to_skill
agentskills validate "$PWD"
pytest --cov=history_to_skill --cov-report=term-missing
python -m build
twine check dist/*

CI runs the checks across Python 3.10–3.13 and smoke-tests the built wheel. Contributions are welcome; see CONTRIBUTING.md.

If history-to-skill saves you a repository-archeology pass, a star helps other maintainers find it.

License

MIT. Repository content processed by the tool remains subject to its original license and access rules.