history-to-skill

<div align="center"> # history-to-skill **Turn GitHub history into a cited maintainer skill for your coding agent.** [](https://github.com/Mandolaro/history-to-skill/actions/workflows/ci.yml) [](https://pypi.org/project/history-to-skill/) [](https://pypi.org/project/history-to-skill/) [](LICENSE) </div> 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](examples/flask/README.md). ## Get started in 30 seconds Install the CLI, MCP server, and Agent Skill: ```bash uv tool install 'history-to-skill[mcp]' history-to-skill install --platform codex codex mcp add history-to-skill -- history-to-skill-mcp ``` Then ask your coding agent: ```text /history-to-skill pallets/flask ``` Claude Code and Cursor users can select their own skill directory convention. See the [coding-agent setup](docs/CODING_AGENTS.md) for their MCP configuration: ```bash 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`, run `pipx install 'history-to-skill[mcp]'`. The MCP server exposes three stateless tools: collect repository evidence, query the evidence graph, and inspect an existing bundle. Every call has explicit inputs; no hidden conversation or server session is required. ## What you get The read-only collector produces a bounded evidence bundle: ```text 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: ```bash history-to-skill pallets/flask flask-maintainer --output ./history_skill_work ``` For an existing checkout: ```bash 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](docs/ARCHITECTURE.md), [evidence format](docs/EVIDENCE_FORMAT.md), [coding-agent integration](docs/CODING_AGENTS.md), [live benchmarks](docs/BENCHMARKS.md), and [research notes](docs/RESEARCH.md). ## 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 ```bash 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](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.