Metadata-Version: 2.4
Name: history-to-skill
Version: 0.3.0
Summary: Turn GitHub history into cited repository-maintenance skills for coding agents.
Project-URL: Homepage, https://github.com/Mandolaro/history-to-skill
Project-URL: Issues, https://github.com/Mandolaro/history-to-skill/issues
Author: Mandolaro
License: MIT
License-File: LICENSE
Keywords: agent-skills,codex,coding-agents,developer-tools,evidence-graph,github,graph-rag,knowledge-graph,repository-analysis,repository-mining,software-maintenance
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.28
Requires-Dist: networkx<4,>=3.2
Requires-Dist: scipy<2,>=1.11
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: skills-ref==0.1.1; (python_version >= '3.11') and extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# history-to-skill

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

[![CI](https://github.com/Mandolaro/history-to-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/Mandolaro/history-to-skill/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/Mandolaro/history-to-skill)](https://github.com/Mandolaro/history-to-skill/releases)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](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.

![A connected slice of the Flask repository maintenance evidence graph](docs/assets/flask-evidence-graph.png)

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 and register the skill:

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

Then ask your coding agent:

```text
/history-to-skill pallets/flask
```

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

```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`, install directly from the same GitHub URL.

## 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),
[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.
