🤖 Codex Skill Miner

Deterministically discover, qualify, and document reusable AI engineering workflows from validated Codex sessions and explicit Git evidence.

The bundled demo analyzes six canonical sessions, discovers four exact workflow groups, and qualifies one evidence-backed workflow candidate.

View the generated demo report — no setup required

🚀 Try the Demo

git clone https://github.com/obscrivn/codex-skill-miner.git
cd codex-skill-miner
uv sync --frozen --dev
uv run skill-miner demo --open

The demo runs entirely offline from bundled canonical sessions and a portable Git bundle. It writes evaluation.json and one qualified workflow directory containing workflow.json (authoritative evidence), workflow.md (concise technical artifact), and workflow.html (standalone judge report).

Why This Matters

AI-assisted engineering sessions often disappear once a task is complete. Codex Skill Miner identifies repeated, validated engineering patterns using deterministic Git and test evidence rather than AI interpretation. It produces auditable workflow artifacts that are candidates for future human-reviewed skill promotion—not generated skills.

Project Story

Codex Skill Miner was developed through milestone-based human–Codex collaboration.

Read the Hackathon Engineering Journal

The journal records architecture decisions, implementation reviews, validation evidence, human approvals, and lessons learned across the project.

What the Demo Proves

• Six canonical sessions are loaded offline from sample data.
• Four exact workflow fingerprints are discovered.
• One workflow qualifies with three independent supporting commits.
• Repeated runs produce deterministic evidence and presentation artifacts.

How It Works

1. Validate canonical session records and resolve explicit full Git SHAs.
2. Canonicalize ordered activities and compute SHA-256 fingerprints.
3. Group only exact matches and apply fixed recurrence, success, and completeness gates.
4. Write deterministic evaluation.json, workflow.json, workflow.md, and workflow.html artifacts.

The core is offline-first: it has no network or OpenAI runtime dependency. Qualification is evidence-before-AI and uses no ranking or similarity logic.

Current Capabilities

• Strict normalized-JSON session loading and deterministic dataset ingestion.
• Explicit Git commit resolution with no timestamp, path, branch, or fuzzy attribution.
• Canonical activity workflow fingerprints and exact grouping.
• Fixed, integer-based qualification gates and rationale codes.
• Deterministic technical and human-facing workflow artifacts.

Not Yet Implemented

• Workflow similarity or ranking
• Native Codex transcript ingestion
• Automatic promotion or SKILL.md generation
• OpenAI runtime integration or semantic enrichment
• Hosted services, databases, and telemetry

Research Hypothesis

Can successful AI engineering workflows be automatically discovered, validated, and promoted into reusable skills?

This MVP tests the first two parts with explicit evidence. Promotion remains a future human-approved step.

AI Assistance Statement

OpenAI Codex and GPT-5.6 were used during planning, implementation, review, debugging, validation, and documentation. They are development tools, not runtime dependencies: the project operates offline with no OpenAI API key.

Codex accelerated architecture exploration, implementation, testing, and documentation. Human decisions defined the research hypothesis, architecture, qualification policy, milestone scope, and final commit approval. See docs/JOURNAL.md for the detailed collaboration record.

Development and Validation

Requirements: Python 3.10+, uv, and Git. The project is currently tested on macOS.

uv run --offline pytest -q
uv run --offline ruff check .
python3.10 -m compileall -q src tests

Current verified result: 113 passed.

For command reference, fixture workflows, validation details, and repository skills, see DEVELOPMENT.md. The approved milestone plan is docs/PLAN.md.

Built With

Python, uv, Pydantic, Typer, Git, JSON, Pytest, Ruff, OpenAI Codex, and GPT-5.6.

License

Released under the MIT License.