Menu
Search `.agents/` durable knowledge using a local JSON index generated from markdown sources. Use `index-docs.py` to refresh search data, and optionally run docs-compile when you also want durable section index files regenerated.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Regenerate optional durable docs indexes and rebuild docs-search cache from local markdown sources. Use after editing `.agents/docs/` (any section), and before maintenance passes that validate index alignment.
Check the `.agents/` knowledge layer for duplication, contradiction, staleness, oversized guidance, broken or stale links, missing index coverage, uncategorized or misplaced knowledge, and consistency between `decisions/` and `troubleshooting/` indexes and their entry files. Use as a periodic maintenance pass.
Read a completed temporary session bundle from `.agents/sessions/` and distill durable repo knowledge into `.agents/` files. Use only after task-closeout has produced a bundle and when the goal is to separate stable guidance from temporary task notes.
Use whenever working with maintainer plans under .agents/docs/plans/. Covers reading a plan before implementation, creating or scaffolding a plan, and updating status or body during or after work. Trigger when the user asks to plan, scope deferred work, check what is planned, or record a plan. Also trigger at the start of implementation to see whether a plan already exists.
Capture the current task into a structured temporary session bundle under `.agents/sessions/` so a learning agent can later distill durable repo knowledge. Use for completed, blocked, or abandoned tasks with meaningful changes, debugging, validation, or reusable lessons.
Scaffold a new maintainer plan under `.agents/docs/plans/<id>.md` with valid YAML frontmatter, collision-checked ids, optional body stub sections (link decisions in a
| name | docs-search |
| description | Search `.agents/` durable knowledge using a local JSON index generated from markdown sources. Use `index-docs.py` to refresh search data, and optionally run docs-compile when you also want durable section index files regenerated. |
Search durable guidance under .agents/ with a local JSON index.
pip install pyyaml)From the target repository (or any subdirectory under it):
python3 .agents/skills/docs-search/scripts/index-docs.py
python3 .agents/skills/docs-search/scripts/search-docs.py "auth troubleshooting"
If the optional docs-compile skill is installed, you can refresh durable section indexes and search index together:
bash .agents/skills/docs-compile/scripts/docs-compile.sh
Default search output lists up to 5 matches; use --limit 3 for top-3.
index-docs.py so docs-search-index.json reflects every *.md under .agents/docs/ (plus playbooks and AGENTS.md as before).search-docs.py "<query>" to get ranked results (title, short description, path).deployment stepsauth errorsknowledge lintpython3 .agents/skills/docs-search/scripts/index-docs.py.bash .agents/skills/docs-compile/scripts/docs-compile.sh (if installed; see .agents/skills/docs-compile/SKILL.md).index-docs.py --dry-run prints sample JSON only and does not write docs-search-index.json.index-docs.py --agents-root /path/to/.agents overrides auto-discovery (equivalent to AGENTS_ROOT=/path/to/.agents).search-docs.py --agents-root /path/to/.agents matches the indexer when the skill runs from outside that repo's .agents/skills/docs-search/.search-docs.py --limit 3 returns fewer matches (default is 5).docs-search-index.json is a repo-local cache under the target checkout's .agents/skills/docs-search/ (written by index-docs.py). search-docs.py loads that path when it can resolve that checkout's .agents/ from the working directory or AGENTS_ROOT / --agents-root, so search stays scoped to the repo even if the skill definition lives elsewhere.docs-search-index.json should remain gitignored.