Files
repoctl/.claude/skills/kdb-table/SKILL.md
T
Alexander BaranovandClaude Opus 5 39c7da3eb1 feat(kdb-table): render a knowledge base as a table a human can read
База знаний машиночитаема и длинна: чтобы ответить «что там вообще есть»,
приходилось читать файл целиком. Теперь есть отдельный вывод для человека.

- `stewardship.kdb_table` - модуль, а не файл рядом со скиллом: `skills install`
  переносит только SKILL.md, поэтому скрипт в каталоге скилла не доехал бы до
  репозитория, куда скилл поставили. Как модуль он доступен везде, где есть
  repoctl: `python -m stewardship.kdb_table --repo <path>`.
- Путь к базе знаний не угадывается: берётся `spec.knowledge.entrypoint` из
  `ops/contract.yaml` целевого репозитория, с откатом на `kdb/kdb.yaml`. Значит
  работает на любом adopted-репозитории, а не только там, где путь канонический.
- Репозиторий без базы знаний получает одну строку и нулевой код возврата,
  а не трейсбек.
- Читает через `stewardship.io`, то есть тем же ruamel, что и остальной код -
  новой зависимости нет.
- Вне командной поверхности CLI намеренно: контракт `repoctl` - машинный вывод,
  а это пособие для чтения. Спецификацию менять не пришлось.

Скилл `kdb-table` зарегистрирован в SKILLS, поэтому расходится штатным
`repoctl skills install` вместе с остальными тремя. Он тонкий: зовёт модуль,
печатает markdown как есть и отправляет за контекстом под задачу в
`repoctl context --intent`.

Проверено: 156 тестов, mypy strict чист, validate на самом репозитории success.
Два новых теста закрепляют чтение entrypoint из контракта (включая нестандартный
путь) и внятный отказ при отсутствии базы.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-27 12:23:32 +03:00

44 lines
1.8 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
python -m stewardship.kdb_table --repo <path>
```
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. If the
repository has no knowledge base, it says so and exits cleanly.
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.