Files
repoctl/.claude/skills/kdb-table/SKILL.md
T
Alexander BaranovandClaude Opus 5 c10df0e3af feat(cli): add repoctl kdb, the one command whose human output is content
Обзор базы знаний жил как `python -m stewardship.kdb_table` - работало, но не
как остальной инструмент. Теперь это обычная подкоманда:

    repoctl kdb --repo .

Вписана в контракт, а не рядом с ним: `--output json|yaml` возвращает штатный
конверт с `stewardship/knowledge-overview@0.1` внутри, находки уходят в stderr,
коды возврата прежние (0, и 3 при отсутствии базы знаний).

Одно осознанное отличие от прочих команд: `--output human` печатает саму
таблицу, а не строку статуса. Для `emit` это не исключение - параметр
`human_renderer` был предусмотрен и до сих пор не использовался. Вопрос «что в
базе знаний» отвечается содержимым; строка «kdb: success» на него не отвечает.
Таблица идёт в stdout, поэтому `repoctl kdb > kdb.md` даёт чистый markdown.

Точка входа берётся из `spec.knowledge.entrypoint` контракта с откатом на
`kdb/kdb.yaml` - репозиторий, держащий базу в другом месте, не будет объявлен
не имеющим её.

Скилл kdb-table переписан на команду вместо вызова модуля. docs/repoctl.md
получил раздел. Спецификацию править не пришлось: закрытого перечня команд она
не содержит.

Тесты: три на CLI (таблица в stdout и находки в stderr, конверт в json, отказ с
кодом 3), плюс прежние два на разбор entrypoint. 159 passed, mypy strict чист.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-27 13:07:36 +03:00

48 lines
2.0 KiB
Markdown

---
name: kdb-table
description: Show a repository's knowledge base (its KnowledgeBase entrypoint) to a human as a compact Markdown table of topics, intents and documents. Use when asked what is in the kdb, which topics or intents exist, where a topic routes, what can be passed to `repoctl context`, or for an overview of the knowledge base. Read-only.
---
# kdb-table
Thin wrapper. The knowledge base is machine-readable and long: reading the whole
file to answer "what is in there" is the thing this skill exists to avoid.
```bash
repoctl kdb --repo <path>
```
Like every other command it emits a result envelope; `--output human` renders
the table instead of the usual one-line outcome, and findings still go to stderr,
so piping stdout gives clean Markdown. The entrypoint is read from the
repository's own `ops/contract.yaml`
(`spec.knowledge.entrypoint`), falling back to `kdb/kdb.yaml`, so no path needs
to be guessed and the same command works on any adopted repository. A
repository with no knowledge base gets a `KNOWLEDGE_ENTRYPOINT_MISSING` warning
and exit code 3, not a traceback.
Print the Markdown it emits as-is; do not paraphrase it. Two tables:
- **topics**, by descending `priority`: id, declared intents, the documents the
topic routes to, and the top-level keys of its `data` (what facts sit inside);
- **documents**: id, path, role, status. `stale` is marked `(!)` - such a
document is out of date, and `repoctl context` warns about it when it hands
it over.
## When an overview is not what is wanted
This answers "what exists". To get only what a specific task needs, take an
intent from the Intents column and ask the tool instead:
```bash
repoctl context --repo <path> --intent <intent>
```
An unknown intent is answered with the closest known ones, so the table is
mainly for the human - an agent can afford to guess once.
## Out of scope
It neither edits nor validates the knowledge base. Schema conformance is
`repoctl validate --repo <path>`; run that after editing the entrypoint.