/terrain-knowledge-skill

name: terrain-knowledge-skill
description: Use when a coding agent needs project knowledge from Terrain .terrain/ assets. Guides layered reading of context, private knowledge, and repomix index.
version: 1.2.0

Terrain Knowledge Skill

Terrain stores **AI knowledge assets** under **`.terrain/`** in this repository (not a global `~/.terrain/knowledge` directory). The desktop app registry at `~/.terrain/registry.json` only maps slugs → repo paths.

Load **`rtk-skill`** when you need to run shell commands during investigation (git, grep repomix file, tests). Resolve tools via **conventional paths** (`~/.terrain/bin/…`) with `bunx`/`npx` fallback — see `rtk-skill` / `codegraph-skill`.

Knowledge layers (mandatory order)

1. **Architecture** — `.terrain/agent/context.md`

• Module map, core flows, system boundaries, tech stack
• Check `.terrain/agent/context-meta.json` or `meta.json` for asset timestamps
• Read directly (short); no RTK needed

2. **Private domain** — `.terrain/knowledge/**/*.md`

• Business glossary, internal frameworks, APIs, scaffolding guides
• Team-maintained markdown; read in filename sort order when surveying

3. **Structured meta** — `.terrain/agent/meta-inputs.md`

• Compiled from `terrain-meta.json` and `knowledge/` scans

4. **Source index** — see `repomix-context-skill`

• Local `.terrain/agent/repomix.md` (gitignored; regenerate via Terrain scan)

Knowledge freshness (mandatory before architecture answers)

Before trusting `context.md` for module/architecture questions:

~/.terrain/bin/terrain tools freshness --project <slug>
# or: bunx @terrain-ai/cli tools freshness --project <slug>

This recomputes when stale and writes `.terrain/.meta/freshness.json`. **Do not** only read that JSON statically — it is a local cache snapshot.

| Score | Rule | |-------|------| | `< 50` | Do not rely on macro context; use `repomix-context-skill` | | `50–69` | Cross-check with repomix grep or `codegraph-skill` | | `≥ 70` | Architecture context is generally reliable |

On conflict: **repomix source slices > codegraph > agent/context.md > human/**

For symbol impact/callers, also see `codegraph-skill` (CodeGraph `status` can lie; use `terrain tools codegraph-drift`).

Query workflow

Task received
  → freshness check (architecture tasks)
  → Read context.md (or relevant section)
  → If business/internal terms → read knowledge/*.md
  → If symbol / call graph → codegraph-skill
  → If implementation / source → repomix-context-skill
  → If shell/git/test needed → rtk-skill (prefix with rtk)

Rules

• **Do not** invent module names that contradict `context.md` or `meta-inputs.md`
• **Do not** read the entire live repository tree when indexed assets exist
• **Do not** load full `repomix.md` into context — grep slices only (`rtk grep` on the file is OK)
• Prefer `.terrain/` over guessing project structure

Private knowledge directory

`.terrain/knowledge/` — developers add markdown here; Terrain scans on context generation.

Example files:

• `00-glossary.md` — domain terms
• `10-internal-framework.md` — internal libs
• `20-api-usage.md` — internal APIs
• `30-scaffolding.md` — project generators

Human docs (optional)

`.terrain/human/` — Litho-generated docs for humans; useful for onboarding context but denser than `context.md`.

Related skills

| Skill | When | |-------|------| | `repomix-context-skill` | Source code from repomix index | | `codegraph-skill` | Callers, callees, impact | | `rtk-skill` | All verbose shell commands |