Agents are easy to overload with skills. You see a useful SKILL.md, install it, try another one, keep a project-specific helper around, and after a while the skill catalog becomes a quiet layer of prompt debt.

Progressive disclosure helps because the full skill body is loaded only when needed. But the catalog still matters: names, descriptions, paths, and availability metadata are repeatedly exposed to new conversations, compacted conversations, and skill-selection context. Unused skills do not just sit on disk. They consume tokens, inject stale semantics, add decision noise, and make it harder for an agent to choose the right capability consistently.

forget is a local, read-only audit tool for agent skills. It scans installed SKILL.md files and local session history, then answers with evidence: which skills are actually used, which are never used, which are stale, which are low-frequency but high-cost, and which look duplicated.

The MVP never deletes, moves, or archives a skill. It produces a report and review hints so you can decide what to keep, merge, move into a repo, or clean up.

• Token budget: skill descriptions and catalog metadata can occupy context even when full skill bodies are not loaded.
• Semantic hygiene: stale or experimental skills can bias the agent with old assumptions, obsolete workflows, or overly broad instructions.
• Selection quality: large overlapping catalogs make skill routing noisier and less stable.
• Prompt debt: skills accumulate like dependencies. Without evidence, cleanup becomes guesswork.
• Scope control: some skills belong globally, while others should live only in one repository.
• Auditability: usage decisions should come from session evidence, not memory or intuition.

• Scan Codex, Claude Code, and generic text/JSON session logs.
• Discover global, plugin-cache, and project-local SKILL.md files.
• Cache scan state in SQLite, skip unchanged sessions, and parse only appended tails for append-only sessions.
• Detect tool_call, skill_file_read, assistant_declaration, and path_reference evidence.
• Ignore false positives from available-skills catalogs.
• Output terminal summaries, JSON, Markdown, and a read-only TUI.
• Mark skills as never_used, stale, low_frequency, or duplicate_candidate.
• Split usage by agent domain: Codex, Claude, and unknown/custom.
• Count how many repositories used each global skill, and list those repositories in the TUI detail pane.
• Show evidence details in the TUI, including timestamps and the user prompt before a skill call.

• Language: Rust 2024
• CLI: clap
• TUI: ratatui + crossterm
• Database: SQLite via rusqlite, with WAL enabled by default
• Scanning: ignore
• Serialization: serde / serde_json
• Time handling: time
• Tests: cargo test, assert_cmd, tempfile

Install Rust stable first.

cd D:\Code\forget
cargo build

Run the development build:

cargo run -- scan

Install into your Cargo bin directory:

cargo install --path .
forget scan

forget scan

By default, forget performs an incremental scan of common local skill and session directories, updates the SQLite index, and prints a terminal summary. It does not write JSON or Markdown unless requested.

Default skill roots:

• ~/.codex/skills
• ~/.agents/skills
• ~/.claude/skills
• ~/.codex/plugins/cache
• .agents/skills in the current directory
• .codex/skills in the current directory
• project-local .agents/skills, .codex/skills, and .claude/skills discovered from historical Codex session cwd metadata

Default session roots:

• ~/.codex/sessions
• ~/.claude/projects
• ~/.claude/history.jsonl

forget scan --full-rescan
forget tui --full-rescan

--full-rescan is a global option for commands that perform a live scan: scan, unused, detail, and tui.

Normal incremental scans:

• Skip sessions whose mtime and size are unchanged.
• Resume JSONL/text sessions from the previous byte offset when the file is append-only and the checkpoint hash matches.
• Fall back to a full parse when a file shrinks, is rewritten, has a mismatched checkpoint, ends without a complete line, or when detector/skill inventory changes require a conservative scan.

forget scan --json target\forget-report.json
forget scan --markdown target\forget-report.md

JSON is useful for scripts and downstream tooling. Markdown is useful for manual review, issues, or documentation.

forget scan --no-default-roots --root D:\skills --sessions D:\sessions

--root can be passed multiple times for skill roots. --sessions can point to multiple session roots or individual session files.

forget unused
forget unused --days 90
forget unused --json target\unused.json

unused lists rows whose recommendation is not keep, including never-used skills, stale skills, low-frequency high-cost skills, and duplicate candidates. --days controls the stale threshold. The default is 60.

forget detail rust-pro
forget detail D:\skills\rust-pro\SKILL.md

Live detail performs an incremental scan first, then reads the matching skill report and evidence metadata from SQLite. It prints the session file, event index, line number, timestamp, evidence type, confidence, and ignored reason.

You can also inspect an exported JSON snapshot:

forget detail rust-pro --from target\forget-report.json

--from mode does not rescan and does not read SQLite evidence details. It only shows report rows already present in the snapshot.

forget tui
forget tui --from target\forget-report.json

forget tui refreshes the default live scan, updates the SQLite index, and then opens a read-only dashboard. During startup it shows scan progress, including skill/session phases and scanned/skipped session counts.

Evidence details are lazy-loaded for the selected skill. The TUI does not preload details and prompts for every skill before opening.

TUI shortcuts:

• j / Down: move down
• k / Up: move up
• Enter: enter the detail pane; press Enter again to return to the list
• Esc: return from the detail pane to the list
• PageDown / PageUp: scroll the detail pane
• l: load the next evidence batch, 100 rows at a time
• s: change sort mode
• f: change filter
• w: toggle truncate/wrap display
• q: quit

The main table shows skill name, scope, agent domain, status, usage counts, repository count for global skills, Codex/Claude/Unknown usage counts, description token cost, and recommendation.

Scope labels:

• global
• plugin
• repo:<repo-name>
• custom

The detail pane shows scope, path, description, first/last usage time, token estimates, repository list for global skills, and evidence rows. Live TUI evidence includes timestamp, session file, event index, line number, evidence type, confidence, ignored reason, and the nearest previous user prompt. forget tui --from ... reads only a JSON snapshot and cannot show SQLite/session evidence details.

forget cache clear

This removes the default SQLite database and sidecar files:

• forget.db
• forget.db-wal
• forget.db-shm

Default database path:

%LOCALAPPDATA%\.forget\forget.db

Override it with:

$env:FORGET_DB_PATH = "D:\tmp\forget.db"
forget scan

SQLite is opened with:

• journal_mode = WAL
• foreign_keys = ON
• synchronous = NORMAL

Each skill report row includes:

• name
• path
• agent
• source_type
• description
• usage_count
• session_count
• codex_usage_count
• claude_usage_count
• unknown_usage_count
• first_used_at
• last_used_at
• days_since_last_use
• evidence_count
• estimated_catalog_tokens
• estimated_body_tokens
• global_repo_count
• global_repos
• status
• recommendation

estimated_catalog_tokens estimates only the frontmatter description field. Missing or empty descriptions are 0. Single-line descriptions, indented continuation lines, and YAML block scalars such as description: > or description: | are counted.

estimated_body_tokens is retained to show body size, but the report Cost column and high-cost classification use description/catalog cost.

Common status values:

• used: recently or repeatedly used.
• never_used: no strong or medium usage evidence.
• stale: used before, but last usage is older than the stale threshold.
• low_frequency: low usage count and high catalog token cost.
• duplicate_candidate: same active skill body hash as another skill in the same agent domain.

Common recommendation values:

• keep: keep it.
• review: review manually.
• archive_candidate: consider archiving.
• merge_candidate: consider merging duplicate skills.
• ignore: internal initial value; normal report output should not end here.

forget classifies evidence by type and confidence:

• tool_call: a structured tool call identifies a skill. Strong evidence.
• skill_file_read: a session explicitly reads a matching SKILL.md. Strong evidence.
• assistant_declaration: the assistant explicitly says it is using a skill. Medium evidence.
• path_reference: text only references a skill path. Weak evidence.

Logical usage counts include only strong and medium evidence. Weak evidence remains in evidence_count but does not increase usage_count.

Agent domains are separated:

• Codex-domain skills are matched with Codex sessions.
• Claude-domain skills are matched with Claude sessions.
• Custom roots that cannot be assigned to an agent are treated as unknown/common and participate in explicitly requested scans.

usage_count is the number of valid usage evidence rows for that skill in its agent domain. Multiple reads or declarations in one session count multiple times. session_count is the number of distinct sessions with valid usage. codex_usage_count, claude_usage_count, and unknown_usage_count split usage by session source.

Duplicate detection is scoped by agent domain so that equivalent Codex and Claude skills are not incorrectly flagged as duplicates of each other.

Ignored evidence:

• available-skills catalog listings.

The following reads count as strong skill_file_read evidence when the path maps to a discovered skill:

• Get-Content .agents/skills/<name>/SKILL.md
• .codex/skills/<name>/SKILL.md
• .claude/skills/<name>/SKILL.md
• absolute SKILL.md paths

Broad relative paths such as skills/<name>/SKILL.md are not treated as strong evidence yet because they are too ambiguous across roots.

Batch reads of multiple skill files count as usage. If an agent loaded or studied several skills in one session, each matching skill read is evidence.

Common validation commands:

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo run -- scan --json target\forget-report.json

CLI help:

cargo run -- --help
cargo run -- scan --help
cargo run -- unused --help
cargo run -- detail --help
cargo run -- tui --help

Project structure:

src/
  cli.rs              CLI arguments and command dispatch
  config.rs           default roots, path expansion, scan options
  detection.rs        evidence detection and false-positive filtering
  inventory.rs        skill discovery, frontmatter parsing, token estimates
  pipeline.rs         scan pipeline
  report.rs           classification, filtering, export formats
  store.rs            SQLite schema, upserts, report queries
  tui.rs              read-only Ratatui dashboard
  sessions/           Codex, Claude, and fallback session adapters
tests/
  cli_scan.rs         binary-level integration tests
  fixtures/           synthetic skill fixtures

• forget is local-only and does not upload session contents.
• The MVP never deletes, moves, or archives skill files.
• --since filters output only. It does not limit SQLite index updates.
• --full-rescan bypasses incremental session checkpoints. Use it when you suspect cache drift, after detector upgrades, or when benchmarking.
• --config and --verbose are reserved global options. The MVP configuration surface is CLI flags plus FORGET_DB_PATH.

forget exists because the agent-skill ecosystem is moving quickly. It is complementary to projects that create, publish, install, and evolve skills; it focuses on the cleanup and audit side of the lifecycle.

Related and inspiring work:

• Hermes Agent, especially its self-improving skill loop and progressive-disclosure skill system.
• Hermes Agent skills documentation, which describes skills as on-demand knowledge documents.
• VoltAgent awesome-agent-skills, a large curated collection of agent skills across hosts.
• Supabase agent-skills, a concrete domain-specific skill collection.
• Microsoft skills, another example of vendor-maintained skills, MCP configs, and agent templates.
• The broader SKILL.md / Agent Skills community, including tools that install, manage, and standardize portable agent skills.

Those projects make it easier to grow a skill library. forget helps decide when that library should shrink.