terrain-ask-skill

name	terrain-ask-skill
description	Terrain Ask — query knowledge via terrain CLI when Agent execution mode is ACP.
version	1.2.0

Terrain Ask (ACP mode)

When Terrain runs in ACP Agent execution mode, built-in function tools are unavailable for Ask. Use the terrain tools CLI to access the same knowledge layers.

Resolve the Terrain CLI

Use conventional paths only — never machine-specific absolute paths like /Users/....

On Windows, tools deploy to %USERPROFILE%\.terrain\bin\ (also ~/.terrain/bin/ in Git Bash / PowerShell 7+). Binaries use .exe extensions.

Priority	Command	When
1	~/.terrain/bin/terrain	Terrain desktop / env integration (see existence check below)
2	bunx @terrain-ai/cli	No Terrain install; needs network once
3	npx @terrain-ai/cli	Same as bunx if Bun unavailable

Existence check:

Shell	Check
bash / Git Bash	[ -x ~/.terrain/bin/terrain ] || [ -x ~/.terrain/bin/terrain.exe ]
PowerShell	Test-Path "$HOME\.terrain\bin\terrain.exe"

In examples below, <terrain> means your resolved prefix (~/.terrain/bin/terrain or bunx @terrain-ai/cli).

Storage model

Each project's knowledge lives at {repo}/.terrain/ (versioned with the repository). The desktop app keeps a local registry at ~/.terrain/registry.json — only repo pointers, not knowledge files.

Environment variables (set by Terrain)

Variable	Purpose
TERRAIN_KNOWLEDGE_ROOT	Current project's .terrain/ directory
TERRAIN_PROJECT_SLUG	Current project slug
TERRAIN_REPO_PATH	Repository root (for citations)
TERRAIN_ASK_SKILL	Ask skill directory

CLI without Terrain UI: run inside a Git workspace, or pass --repo-path / set TERRAIN_REPO_PATH.

Three layers (same as native Ask)

Layer	CLI	When
Macro	(preloaded in prompt)	Architecture overview — answer from prompt first
Meso	terrain tools read-context	One section of agent/context.md
Micro	grep-pack → read-pack-file	Source code from repomix pack

Never read the live repository filesystem. The repomix pack is authoritative for code.

CLI reference

All commands output JSON to stdout.

# From repository root (auto-detects workspace), or:
# <terrain> --repo-path /path/to/repo tools ...

# List indexed projects
<terrain> tools list-projects

# Repomix pack metadata
<terrain> tools pack-meta --project {slug}

# Grep agent/repomix.md
<terrain> tools grep-pack --project {slug} --pattern "struct Foo"

# Read a file slice from the pack (≤150 lines recommended)
<terrain> tools read-pack-file --project {slug} --file src/main.rs --start-line 1 --end-line 80

# Architecture context (optional section)
<terrain> tools read-context --project {slug}
<terrain> tools read-context --project {slug} --section "核心流程"

# Human / structured docs (paths relative to .terrain/)
<terrain> tools search --query "authentication" --project {slug}
<terrain> tools read-doc --project {slug} --path human/1.概述.md

Workflow

1. Use macro context from the user message when sufficient.
2. For architecture sections not preloaded → read-context --section "…".
3. For implementation → grep-pack with a focused pattern, then read-pack-file with line range.
4. Cite paths as src/foo.rs:42 from pack line numbers.
5. Do not run identical CLI commands twice with the same arguments.

Limits

• read-pack-file: pass --start-line and --end-line; max ~150 lines per call.
• search: limit 5–10 hits for Ask.
• Do not dump entire repomix.md.