nuggetindex-skill

Zero-install fact governance for your coding agent. One skill that teaches Claude Code, Codex, Cursor, and other agents the NuggetIndex method (SIGIR '26): audit RAG output for stale and conflicting facts, keep a time-aware fact ledger, and scale up to the real index when the corpus outgrows the agent.

npx skills add searchsim-org/nuggetindex-skill

Why

Ask a naive RAG stack "Who is Apple's CEO?" and it may answer Steve Jobs — an old passage ranked highest. Ask about a company two sources disagree on, and it silently picks whichever passage embeds better. NuggetIndex fixes both by treating knowledge as atomic facts with explicit temporal validity [start, end), lifecycle states (active / deprecated / contested), and provenance — and by surfacing conflicts instead of hiding them.

The insight behind this skill: the parts of that pipeline the package delegates to an LLM (fact extraction, conflict judging, auditing) your agent can do natively — no install, no API keys. The parts that need real infrastructure (persistent hybrid retrieval over thousands of facts, HTTP serving, reproducible evals) escalate to pip install nuggetindex.

What the skill does

Rung	Trigger	What happens	Install
1. In-context audit	"Is my RAG returning stale facts?"	Agent extracts facts from your retrieved passages, checks validity against query time, flags stale/contested with evidence	none
2. Project fact ledger	Ongoing project needs governed facts	Agent maintains `nuggets.jsonl` in the package's exact schema, running dedup + conflict detection on every append	none
3. Real index	Corpus > ~50 docs, persistence, serving, LangChain/LlamaIndex/Haystack	Agent drives the `nuggetindex` CLI/API; your hand-built ledger imports unchanged	`pip install nuggetindex`

Same method at every rung — the ledger format is bit-compatible with the package's Nugget JSON, so escalation is an import, not a migration.

Install

Claude Code

/plugin marketplace add searchsim-org/nuggetindex-skill
/plugin install nuggetindex@nuggetindex-skill

or manually:

git clone https://github.com/searchsim-org/nuggetindex-skill
cp -r nuggetindex-skill/skills/nuggetindex ~/.claude/skills/

Verify: ask Claude "audit these passages for stale facts" — it should announce the nuggetindex skill.

Codex

Tell Codex:

Fetch and follow the instructions from https://raw.githubusercontent.com/searchsim-org/nuggetindex-skill/main/.codex/INSTALL.md

or manually:

git clone https://github.com/searchsim-org/nuggetindex-skill ~/.codex/nuggetindex-skill
mkdir -p ~/.agents/skills
ln -s ~/.codex/nuggetindex-skill/skills/nuggetindex ~/.agents/skills/nuggetindex

Any agent (npx skills)

npx skills add searchsim-org/nuggetindex-skill        # detects installed agents

Per-project

Copy skills/nuggetindex/ to .claude/skills/nuggetindex/ (Claude Code) or .agents/skills/nuggetindex/ (Codex) inside the repo.

Example

You: My support bot keeps telling users our old pricing. Here are the passages the retriever returned for "what does the Pro plan cost" — can you check them?

Agent: (nuggetindex skill) Extracted 6 facts across 4 passages. At query time 2026-07-18:

stale — passage 2 asserts (Pro plan, price, $29/mo) valid [2023-01 → 2025-03); superseded

contested — passages 1 and 4 disagree on (Pro plan, price): $39/mo [2025-03 →) vs $35/mo [2025-06 →), 1-vs-1 evidence — you should adjudicate

passage 3 is consistent

Summary: 1 stale passage, 1 cross-source conflict. Want me to keep a governed fact ledger for the pricing docs so this can't recur?

Structure

skills/nuggetindex/
├── SKILL.md                     # the method + 3-rung decision ladder
└── references/
    ├── extraction.md            # triple extraction + temporal inference rules
    ├── conflict-rules.md        # conflict algorithm, lifecycle, functional predicates
    ├── ledger-format.md         # nuggets.jsonl schema (package-compatible)
    └── package.md               # pip escalation: full CLI/API reference

Citation

If you use this skill or the NuggetIndex method, please cite:

@inproceedings{zerhoudi2026nuggetindex,
  title     = {{NuggetIndex}: Governed Atomic Retrieval for Maintainable {RAG}},
  author    = {Zerhoudi, Saber and Granitzer, Michael and Mitrovi{\'c}, Jelena},
  booktitle = {Proceedings of the 49th International ACM SIGIR Conference
               on Research and Development in Information Retrieval (SIGIR '26)},
  year      = {2026},
  pages     = {2286--2296},
  publisher = {ACM},
  doi       = {10.1145/3805712.3809687},
  url       = {https://dl.acm.org/doi/10.1145/3805712.3809687}
}

Contributing

Issues and PRs welcome. Keep SKILL.md under 500 lines; put detail in references/; every claim about the package must match nuggetindex source.

License

MIT

Nuggetindex Skill

README