---

name: development description: "Safely modify, test, lint, and maintain the Khoj repository as a contributor." disable-model-invocation: true metadata: disco-role: operating license: AGPL 3.0

Khoj Development

Use this sub-skill when a task is about changing Khoj source code, selecting focused tests, preparing local contributor workflows, editing Django models or migrations, updating routers with tests, maintaining docs/client awareness, or respecting development/release script boundaries.

Start Here

• For local setup, Docker-vs-pip development choices, frontend/docs/client awareness, and script boundaries, read development-workflows.md.
• For changed-area-to-test mapping and safe focused commands, read test-selection.md.
• For Django model, migration, admin, adapter, fixture, and database-safety considerations, read migrations-and-models.md.
• For PostgreSQL, admin env vars, frontend/static assets, model/API mocks, ML dependency slowness, and external-service test failures, read troubleshooting.md.
• To map paths or capability names to candidate pytest files without running tests, run select_focused_tests.py.

Safe Workflow

1. Classify the change area before editing: parser/content, search/filter, chat/agent, automation/memory, API/router, Django model/migration, CLI/config, frontend/client, or documentation.
2. Prefer focused tests from the mapping first; reserve full pytest for final confidence or broad refactors, and avoid expensive evals unless explicitly requested.
3. For router changes, update request/response validation, auth/rate-limit behavior, database adapters, and a FastAPI TestClient or async test together.
4. For model changes, plan the Django model edit, migration, admin/adapters impact, fixtures/factories, and rollback/data-migration behavior before touching runtime code.
5. For frontend, docs, desktop, Obsidian, or Emacs-visible changes, update the relevant client/docs surface but do not run release-version mutation scripts.

Boundaries

This sub-skill owns contributor workflows, focused testing, lint/format conventions, model/migration planning, and development-script safety. Route user-facing endpoint contracts to deployment-api, ingestion details to content-indexing, search behavior to search-retrieval, chat/agent payload behavior to chat-agents, and automations or memory product behavior to automations-memory.

Safety Notes

• Do not use khoj --help as a harmless parser check in an unconfigured checkout; import khoj.utils.cli.cli or run parser-only tests instead.
• Do not run scripts/dev_setup.sh automatically for an agent task; it installs dependencies, builds clients, and mutates git hooks.
• Do not run scripts/bump_version.sh unless the user is explicitly performing a maintainer release; it edits version files, commits, and tags.
• Do not start Docker services, migrate a real database, install packages, or run external-service/chat-quality tests unless the user has approved operational side effects.