# Ask My Repo > Three-mode repo knowledge skill for ANY codebase: INGEST builds cited knowledge files (AGENTS.md + docs/ARCHITECTURE.md) so any AI agent can understand the codebase without re-searching it; UPDATE re-verifies and merges changes into existing knowledge without overwriting; QUERY answers natural-language questions about the repo by reading the knowledge first, then drilling into code only when needed, with file:line citations. Use whenever the user asks to ingest/onboard/understand a repo, update or refresh repo knowledge/docs, or asks any question about a codebase's architecture, modules, conventions, where things live, or how something works — even if they don't say "ask-my-repo". Works on any repo, no hardcoded paths. Trigger phrases: "ask my repo", "query the codebase", "ingest this repo", "update repo knowledge", "how does X work in this repo", "where is X", "explain the architecture", /ask-my-repo. - Skill: `silkyland/ask-my-repo` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add silkyland/ask-my-repo` - Raw SKILL.md: https://api.skillmd.com/api/skills/silkyland/ask-my-repo/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: silkyland (https://skillmd.com/u/silkyland) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/silkyland/ask-my-repo --- # Ask My Repo A shared, repo-agnostic knowledge skill with three modes. It gives any AI agent a fast, cited understanding of any codebase — without the agent having to re-explore the whole tree on every question. ``` ask-my-repo/ ├── SKILL.md (this file — mode selector + shared rules) └── references/ ├── ingest.md (full ingest process) ├── update.md (re-verify + merge process) └── query.md (answering process + citation rules) ``` ## The Prime Directive (applies to all modes) > **No claim without evidence.** Every statement that lands in a knowledge > file, and every answer given in query mode, carries a `file:line` > citation, a command you actually ran, or an explicit `UNVERIFIED` tag. > A convention is only a convention with **two or more examples and no > counterexample** — otherwise report it as an inconsistency. This is what > makes the knowledge trustworthy enough to skip re-searching. ## Mode selection Resolve the mode from the argument hint, the user's phrasing, and the state of the target repo. State which mode you picked and why in your first response line, e.g. `Mode: ingest (no AGENTS.md found in ./)`. | User says / situation | Mode | |---|---| | "ingest this repo", "onboard", "understand this codebase", "generate AGENTS.md", no knowledge files exist | **ingest** | | "update the docs/knowledge", "refresh AGENTS.md", knowledge files exist but may be stale | **update** | | "how does X work", "where is Y", "explain the architecture", any question about the repo | **query** | | Ambiguous: if knowledge files exist, prefer **query**; if not, **ingest** | ### Target resolution (all modes) - If a `[project-root]` argument is given, treat that path as the repo root. - Otherwise use the current working directory. - Never assume a hardcoded path. Always derive the root from the argument or cwd, and state it explicitly: `Target: /abs/path/to/repo`. - Knowledge files live at `/AGENTS.md` and `/docs/ARCHITECTURE.md` by default. If the repo already keeps agent knowledge elsewhere (`CLAUDE.md`, `.cursorrules`, `docs/ROADMAP.md`, …), treat those as the canonical knowledge set and merge into them — do not create competing files. ## Mode: ingest → read `references/ingest.md` Build the initial knowledge set from zero. Deep parallel read of the codebase, extract conventions (2+ examples each), verify build/test/run commands by running them, follow one real feature end to end, then write `AGENTS.md` + `docs/ARCHITECTURE.md` with every fact cited. Nothing is deleted. Read the reference for the full 8-step process. ## Mode: update → read `references/update.md` Existing knowledge files are the starting point, not a blank page. Re-verify every claim against current code, mark stale ones, merge new findings in place. Never overwrite — merge. Show the user a diff summary of what changed. Read the reference for the verify-then-merge process. ## Mode: query → read `references/query.md` Answer natural-language questions about the repo. Read the knowledge files first (they exist precisely so you don't re-explore), then drill into code only when the question isn't fully covered by the docs. Always cite `file:line`. If the knowledge files don't exist, offer to run ingest first. Read the reference for the answering process and citation rules. ## Shared rules (all modes) 1. **Cite or tag.** `file:line` for code facts, the command for verified commands, `UNVERIFIED` for anything you couldn't check. No bare claims. 2. **Two examples make a convention.** One example is an observation; two with no counterexample is a convention. Report counterexamples as inconsistencies, not as the rule. 3. **Run what you write.** Build/test/lint commands are only "verified" after you actually ran them and captured the exit code. Reading a `package.json` script is not verification. 4. **Merge, don't overwrite.** In update mode especially, preserve true facts and only change what's stale. In ingest mode, merge into any trivial existing files rather than creating competing ones. 5. **Nothing destructive.** Never delete existing knowledge files or code. Ingest creates; update edits in place with diffs; query never writes. 6. **Stay portable.** No hardcoded paths, no repo-specific assumptions in the skill itself. All repo specifics come from reading the actual repo. ## Output conventions - Use `` and `` tags when referencing files so they're clickable. - For ingest/update, end with a short report: files written/changed, command verification results, any `UNVERIFIED` items, and suggested next steps. - For query, end with a direct answer plus citations; if the answer is partial, say what's missing and where to look.