Metadata-Version: 2.4
Name: codex-skill-report
Version: 0.1.0
Summary: Analyze inferred skill invocations in retained Codex sessions
Author: egornomic
Author-email: egornomic <git@egornomic.xyz>
License-Expression: 0BSD
License-File: LICENSE
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Codex Skill Report

Analyze retained Codex session transcripts and estimate how often each skill was
self-invoked, explicitly requested, or ambiguously mentioned.

## Run with `uvx`

From anywhere after publishing to PyPI:

```bash
uvx codex-skill-report
```

From a local checkout:

```bash
uvx --from . codex-skill-report
```

Useful output modes:

```bash
uvx codex-skill-report --details
uvx codex-skill-report --json --output report.json
uvx codex-skill-report --csv --output report.csv
uvx codex-skill-report --markdown --output report.md
```

Use `--codex-home PATH` to scan a non-default Codex data directory. The default
is `$CODEX_HOME`, falling back to `~/.codex`.

## How counting works

A `SKILL.md` read is the strongest event available in retained transcripts. It
is counted once per skill, agent, and turn, then classified as:

- **Self**: the active request did not name the skill.
- **Requested**: the active request explicitly asked Codex to use the skill.
- **Ambiguous**: the request mentioned the skill without clearly asking to use it.

The report separates self-invocations by root agents and subagents. Deleted,
ephemeral, compacted-away, or unsynced sessions cannot be recovered. Wildcard
reads that cannot be attributed to one skill are reported separately. Human
reports show the most recent invocation as a compact relative age; JSON and CSV
retain its exact timestamp. In terminal output, red names identify skills that
previously came from a managed user, system, or plugin root but no longer exist.
Repository-local skill folders are not scanned and remain uncolored when their
availability cannot be determined. When forked transcripts replay an earlier
turn, the report keeps only the earliest occurrence of each skill read.

## Development

```bash
uv sync --all-groups
uv run pytest
uv run ruff format --check .
uv run ruff check .
uv run ty check src
uv build
```
