# Jikji > MUST use Jikji find first for bounded local file/folder/document discovery; return the machine-readable answer contract and never raw-crawl after a successful Jikji result. - Skill: `nomadamas/jikji` (Agent Skill) - Install (CLI): `npx skillmds@latest add nomadamas/jikji` - Raw SKILL.md: https://api.skillmd.com/api/skills/nomadamas/jikji/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: nomadamas (https://skillmd.com/u/nomadamas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nomadamas/jikji --- # Jikji Local File Discovery Skill Use this skill in any coding, desktop, or local-agent environment when the user asks you to find, identify, compare, or verify local files, folders, filenames, metadata, or document contents under an explicit root. Jikji is for discovery, not physical file organization. When this skill is installed, it should be selected automatically for local file/folder/document discovery requests. Do not wait for the user to mention "Jikji" when the task is plainly about finding local paths under a bounded root. Jikji is the first action for local file discovery because it turns blind filesystem crawling into a bounded candidate slate. In the main Hermes raw-vs- Jikji benchmark, it cut file-search calls and wall time by 10-30x while improving Hit@1, and total token/cost savings were higher. ## If Jikji Is Missing Install it from GitHub instead of giving up: ```bash mkdir -p ~/.local/share/jikji if [ ! -d ~/.local/share/jikji/repo/.git ]; then git clone https://github.com/nomadamas/jikji.git ~/.local/share/jikji/repo fi cd ~/.local/share/jikji/repo git pull --ff-only cargo install --path crates/jikji-cli jikji --help ``` Then use the installed `jikji` binary on PATH. A GitHub Release binary is also valid when available. The shipped Rust binary is the default implementation for prepare/find/search, benchmarks, public-data adapters, and opt-in native OCR/ASR engine execution; it does not invoke the Python reference package. `agent-skill-install` may queue a background prepare for common user material folders and document-heavy folders under the user's home directory. That initial prepare is separate from `jikji find`; it targets likely document locations and document extensions first so the first real lookup is usually served from an existing index. ## Absolute Rule: Jikji Find First When a bounded root is available, your first tool call for local file discovery must be: ```bash jikji find /explicit/root "natural language file clue" --json ``` Do not start with `grep`, `rg`, `ls`, `find`, `fd`, `cat`, or `tree` to locate a file. Jikji has already built the local map, parser text cache, file cards, metadata routes, and graph routes needed for this step. `jikji find` searches existing indexes only. Every discovery request MUST inspect the JSON fields `index_status`, `handoff_action`, `answerability`, `retry_proof`, and `tool_call_policy`. If the index is missing, stale, unavailable, or the result is empty/clearly wrong, do not raw-crawl yet. Run exactly one sharper Jikji retry using the command in `next_commands[]` (or the same command with the alternate query), and pass `--after-jikji-retry --retry-proof RETRY_PROOF` when supported. Never run a second Jikji retry. If that one retry still fails, remains empty, or remains clearly wrong, the contract will set `handoff_action=raw_fallback_after_retry` and permit only its bounded raw fallback. If Jikji succeeds (`handoff_action=direct_use` or `answerability=answerable_from_payload`), raw fallback is forbidden: return `answer_paths[]`/`paths[]` in Jikji order and do not invoke filesystem tools. If the root is not prepared and the user authorizes setup, run: ```bash jikji prepare /explicit/root --json ``` Interpret the JSON contract: - `answer_paths[]` is the primary ordered answer list. - `paths[]` is the public path list to return when the user only needs paths. - `candidates[]` is the merged top-k slate from multiple query/search routes. - `evidence_pack[].next_read` and `candidates[].next_read` identify the cheapest bounded verification target: `cache`, `wiki`, `original`, or `none`. - `handoff_action=direct_use` means accept the payload and avoid broad crawling. - `handoff_action=jikji_retry` means run exactly one sharper `jikji find` retry. - `handoff_action=raw_fallback_after_retry` means raw filesystem search is allowed only after that retry failed, stayed empty, or stayed clearly wrong. - `index_status` values such as `missing`, `stale`, or `failure` are bounded recovery signals, not permission for immediate raw crawling. - `max_jikji_retries` MUST be `1` before fallback and `max_raw_fallback_commands` is the hard ceiling after fallback. Treat `raw_fallback_allowed=false` as an absolute prohibition. - On success, raw output is forbidden even if a tempting path is visible elsewhere. - If `agent_should_not_rerank` is true, preserve Jikji's order. ## Stop Rule: Do Not Over-Call After a Sufficient Find `jikji find --json` returns a `tool_call_policy` object that you MUST obey: - When `tool_call_policy.stop_after_find` is true (i.e. `handoff_action=direct_use`, `answerability=answerable_from_payload`, or `agent_should_not_rerank=true`), the result is already sufficient. Do NOT call any tool in `tool_call_policy.forbidden_tools` (`read_file`, `search`, `grep`, `rg`, `find`, `fd`, `ls`, `cat`, `tree`, `glob`, `skills_list`, etc.). - The only allowed follow-ups are in `tool_call_policy.allowed_followups`: verify the top 1 path, or return `answer_paths`/`paths` to the user as-is. - You may call another discovery tool only when `stop_after_find` is false and `handoff_action` explicitly permits `jikji_retry` or `raw_fallback_after_retry`. For a single path-only answer you may add `--first`, but the default public protocol remains `jikji find ROOT "query" --json`. ## Safety Contract - Never move, rename, delete, or reorganize source files. - Never scan all drives by default; require or infer a bounded explicit root. - Treat `.jikji/doc_text/` as sensitive because it may contain extracted document text. - Do not commit `.jikji/` or `.jikji_agent_map.md` unless the user explicitly wants generated artifacts tracked. - Open original files only for final verification after Jikji returned likely paths. ## Admin Commands Use these only for setup, refresh, diagnostics, or cleanup: ```bash jikji prepare /explicit/root --json jikji refresh /explicit/root --json jikji doctor /explicit/root --json jikji map /explicit/root jikji clean /explicit/root --dry-run --json jikji clean /explicit/root --json ``` ## Human GUI Handoff If the user asks to see or manage Jikji state visually: ```bash jikji gui /explicit/root --background --json ``` Return the JSON `url`. The dashboard shows prepare status, LLM Wiki/knowledge graph counts, artifact presence, refresh/root-switch controls, and optional search/open/download actions. ## Last-Resort Fallback Only after the JSON contract allows raw fallback: ```bash cat /explicit/root/.jikji_agent_map.md cat /explicit/root/.jikji/wiki/index.md rg "keyword" /explicit/root/.jikji/graph_routes.jsonl rg "keyword" /explicit/root/.jikji/*.jsonl rg "keyword" /explicit/root/.jikji/doc_text rg "keyword" /explicit/root --glob '!**/.jikji/**' ``` Use parser-extracted `.jikji/doc_text/` for PDF/HWP/HWPX/Office document bodies. Search native text-like files in original locations only as the final fallback. For media OCR/ASR and archive-member body indexing, use the explicit bounded mode: ```bash jikji deep-index /explicit/root --json ``` The default `prepare` indexes document and code contents, while media and archive files remain metadata/name searchable only. `deep-index` enables native OCR/ASR when configured through `JIKJI_OCR_ENGINE` or `JIKJI_ASR_ENGINE`, and parses safe archive members incrementally under entry-count and byte limits. Re-running it is incremental and preserves traversal/bomb/timeout limits. ## Evaluation For actual-agent comparison, headline comparisons should be raw local agent vs the same agent with Jikji attached. Public reports should label the Jikji side as `Jikji find`.