Przejdź do treści
Biblioteka skilli
AI i agenci · Konwersja i formaty

knowledge-index

/knowledge-index

Przebudowuje na żądanie indeks główny i indeksy typów bazy cogni-knowledge, migruje starsze wiki do układu 0.0.8 i naprawia rozjechane obszary zarządzane maszynowo.

Repozytorium
insight-wave ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
19.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 19.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Przebudowuje na żądanie indeks główny i indeksy typów bazy cogni-knowledge, migruje starsze wiki do układu 0.0.8 i naprawia rozjechane obszary zarządzane maszynowo.

Wyzwalacze z opisu

rebuild the indexrebuild the knowledge indexregenerate the wiki indexesrefresh the sub-indexesmigrate my wiki to the curated layout
Oryginalny opis (EN)

Rebuild the curated root index + per-type sub-indexes of a cogni-knowledge base on demand, migrate an EXISTING pre-0.0.8 wiki to the curated layout (control files into wiki/meta/, overview folded into the index intro, flat root split into root-map + sub-indexes, schema 0.0.7→0.0.8), or repair drifted machine-owned regions (theme-scoped ROOT-LINKS, schema lag) on a base already >= 0.0.8. Use this skill whenever the user says 'rebuild the index', 'rebuild the knowledge index', 'regenerate the wiki indexes', 'refresh the sub-indexes', 'migrate my wiki to the curated layout', 'upgrade the wiki lay

Jak działa

  1. When to run
  2. Never run when
  3. Parameters
  4. Workflow
  5. Edge cases
Sekcje z nagłówków SKILL.md, w oryginale · 277 linii, 1 887 słów
Podgląd SKILL.md
---
name: knowledge-index
description: "Rebuild the curated root index + per-type sub-indexes of a cogni-knowledge base on demand, migrate an EXISTING pre-0.0.8 wiki to the curated layout (control files into wiki/meta/, overview folded into the index intro, flat root split into root-map + sub-indexes, schema 0.0.7→0.0.8), or repair drifted machine-owned regions (theme-scoped ROOT-LINKS, schema lag) on a base already >= 0.0.8. Use this skill whenever the user says 'rebuild the index', 'rebuild the knowledge index', 'regenerate the wiki indexes', 'refresh the sub-indexes', 'migrate my wiki to the curated layout', 'upgrade the wiki layout', 'migrate the knowledge base structure', 'repair the knowledge index', 'regenerate the curated front door', 'fix the structural drift', or knowledge-resume / knowledge-health surfaces a schema_version < 0.0.8 migration nudge or a structural-drift verdict."
allowed-tools: Read, Bash, Glob
---

# Knowledge Index

Three related operations on a bound knowledge base, all delegating to the locked
renderers (`sub_index.py`, `root_index.py`) so index-shaping logic lives in one
place:

- **Rebuild** — deterministically (re)render the six per-type sub-indexes
  (`wiki/<type>/index.md`) and the curated root MAP (`wiki/index.md`) from
  current wiki state. Useful after manual page edits, a crashed finalize, or
  any time the indexes look stale. Idempotent: an unchanged wiki re-renders
  byte-identically.
- **Migrate** — converge an EXISTING old-structure wiki (`schema_version <
  0.0.8`) onto the curated layout `knowledge-setup` seeds for new ones:
  control files relocate into `wiki/meta/`, the `overview.md` narrative folds
  into the `index.md` intro, the flat root index splits into root-map +
  per-type sub-indexes, and the schema bumps to `0.0.8`. Dry-run first, always.
- **Repair** — on a base already on the curated layout (`schema_version >=
  0.0.8`), regenerate drifted machine-owned regions keyed on the
  structural-drift class `health.py` emits (not the version floor): a
  theme-scoped `ROOT-LINKS` span stuck on the empty-state sentinel is
  re-rendered via `root_index.py render`, and a lagging `schema_version` is
  reconciled to the current engine schema. Same dry-run-first / `--apply`
  ergonomics as migrate. Idempotent: a non-drifted, current-schema base is a
  `noop`. **Scope boundary:** the script repairs ROOT-LINKS + schema lag; a
  degraded OVERVIEW-NARRATIVE (stuck on the bootstrap placeholder) is
  re-authored by a separate orchestrator step (see 2c) — `root_index.py
  render` carries that block verbatim and never re-authors it.

The migrate split is the lossy transform — human content could be dropped when
the flat root becomes a MAP. It is delegated to `root_index.py render`, which
carries every `MACHINE-OWNED:PORTAL-LEADIN` span and every human
(non-sentineled) lead-in verbatim and drops only the per-page bullets (they
relocate into the sub-indexes). The migrator never re-implements the split.

## When to run

- The user asks to rebuild, regenerate, or refresh the wiki indexes
- `knowledge-resume` surfaced a `schema_version < 0.0.8` migration nudge
- A base predates the curated layout and the user wants the new structure
- After hand-editing wiki pages, to re-derive the indexes from disk
- `knowledge-health` surfaced a `structural_drift` verdict (empty ROOT-LINKS,
  placeholder OVERVIEW-NARRATIVE) or a `schema_version_lag` on a curated base,
  and the user wants the one-command repair (`--repair`)

## Never run when

- The target directory has no `.cogni-knowledge/binding.json` — offer
  `knowledge-setup` instead.
- Mid-pipeline (a `knowledge-finalize` run is active) — finalize renders the
  same indexes itself; a concurrent rebuild just churns the lock.

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--knowledge-slug` | Yes | Slug of the knowledge base. Resolves to `cogni-knowledge/<slug>/` unless `--knowledge-root` overrides. |
| `--knowledge-root` | No | Override the default knowledge-base directory. |
| `--migrate` | No | Run the layout migration instead of a plain rebuild. Dry-run by default. |
| `--repair` | No | Regenerate drifted machine-owned regions (theme-scoped ROOT-LINKS, schema lag) on an already-curated (`>= 0.0.8`) base, keyed on health's structural-drift class. Dry-run by default. Refuses a pre-0.0.8 base (run `--migrate` first). |
| `--apply` | No | With `--migrate`: actually relocate files, render, and bump the schema. With `--repair`: render the regenerated root MAP under the renderer's lock and reconcile `schema_version` to the current engine schema. Without it the run stages proposals and reports, touching nothing live. |

## Workflow

### 1. Resolve the base

1. Resolve `knowledge_root`: `--knowledge-root` if set, else
   `cogni-knowledge/<knowledge-slug>/` relative to the working directory.
2. Read the binding:
   ```bash
   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/knowledge-binding.py read \
       --knowledge-root <knowledge_root>
   ```
   On `success: false`, abort and offer `knowledge-setup`. Do not auto-create.
3. Extract `wiki_path` from the binding. Read
   `<wiki_path>/.cogni-wiki/config.json` for `schema_version` (abort with the
   config error when unreadable — the wiki is the authoritative validator).
   Also derive `OUTPUT_LANGUAGE` from the binding's
   `research_defaults.output_language` (default `en` on a pre-0.1.1 binding or
   an absent key) — this base's default language, threaded to the sub-index
   render so the engine-owned per-theme lead-in fallback reads in-language on a
   non-English base:
   ```bash
   OUTPUT_LANGUAGE=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/knowledge-binding.py" read \
       --knowledge-root <knowledge_root> 2>/dev/null \
     | python3 -c '
   import json, sys
   env = json.load(sys.stdin)
   data = (env.get("data") or {}) if isinstance(env, dict) else {}
   b = data.get("binding") or {}
   print((b.get("research_defaults") or {}).get("output_language") or "en")
   ' 2>/dev/null || printf en)
   ```
4. Resolve the wiki-engine scripts dir (vendored-first):
   ```bash
   . "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-wiki-scripts.sh"
   WIKI_INGEST_SCRIPTS=$(resolve_wiki_scripts wiki-ingest config_bump.py) \
     || abort "cogni-knowledge's vendored wiki-ingest scripts are missing. Reinstall cogni-knowledge, then retry."
   ```

### 2a. Rebuild mode (default)

Requires `schema_version >= 0.0.8` — on an older base, say so and route to
`--migrate` instead (a rebuild against a flat layout would render sub-indexes
the old root never links to).

Render the six sub-indexes, then the root, then the derived perspectives overlay
(the root's count-links and the overlay's facet counts read the same theme
assignment the sub-indexes use, so order matters only for readability — all are
idempotent):

```bash
for t in concepts entities people questions sources syntheses; do
  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/sub_index.py" render \
    --type "$t" --wiki-root "<wiki_path>" --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS" \
    --lang "$OUTPUT_LANGUAGE"
done
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/root_index.py" render \
  --wiki-root "<wiki_path>" --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS"
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/perspectives_index.py" render \
  --wiki-root "<wiki_path>" --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS"
```

Each call returns the standard envelope. Collect per-type `changed` /
`theme_count` from `data` and report one summary line per type, the root, and the
perspectives overlay (`facet_count` instead of `theme_count`):
`<type>: <n> theme(s), <changed|unchanged>` / `perspectives: <changed|unchanged>`.
Any `success: false` → surface the error and stop (the remaining renders are
independent; report what landed). The perspectives overlay (`wiki/perspectives.md`)
re-projects the same pages by 5W1H perspective without changing the canonical
layout; it carries forward narrator-authored facet lead-ins and never clobbers a
hand-authored page.

### 2b. Migrate mode (`--migrate`)

**Dry-run first, always.** Run the migrator without `--apply`:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/migrate-layout.py" \
  --wiki-root "<wiki_path>" --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS"
```

- `action: noop` / `reason: already_migrated` → tell the user the base is
  already on the curated layout; offer a plain rebuild if indexes look stale.
- `action: dry_run` / `reason: relocate_pending` → the base is already curated
  but carries curated-layout repairs (reappeared flat-root control files,
  a missing `wiki/meta/`, or an unfolded overview narrative — see
  `data.conflicts` / `data.meta_missing` / `data.overview_fold_pending`);
  `--apply` runs the relocate-only repair, never the full migration.
- `action: relocated` (after `--apply` on a curated base) → the repair landed;
  report the moved files / recreated meta / fold from the envelope.
- `success: false` with `action: conflicts` → a control file exists at BOTH
  the flat `wiki/` root and `wiki/meta/`; surface the named files — the user
  must compare and remove one copy manually (the engine never auto-clobbers).
- Otherwise present the preview: the planned control-file moves
  (`data.control_files[].action`), the overview-fold verdict
  (`data.overview_fold.action`), and the staged proposal paths
  (`data.staged[].path` — `.cogni-wiki/*-proposed.md`). These staged files are
  the **content diff surface**: point the user at the staged root MAP so they
  can diff it against the live `wiki/index.md` before committing.

Then, only when the user passed `--apply` (or confirms after the preview):

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/migrate-layout.py" \
  --wiki-root "<wiki_path>" --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS" --apply
```

Report from the envelope: control files moved, the overview fold, the rendered
indexes, and `schema_after: 0.0.8`. A second `--apply` is a clean no-op, so
re-running after an interruption is safe.

### 2c. Repair mode (`--repair`)

For a base **already** on the curated layout (`schema_version >= 0.0.8`) whose
machine-owned regions have drifted — the case `knowledge-health` flags as
`structural_drift` / `schema_version_lag` but the `--migrate` path (version-floored)
never reaches. The script repairs two regions; a third (OVERVIEW-NARRATIVE) is an
orchestrator step, below.

**Dry-run first, always.** Run the repair without `--apply`:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/migrate-layout.py" \
  --wiki-root "<wiki_path>" --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS" --repair
```

- `success: false` (pre-0.0.8 base) → the base is not curated; route to
  `--migrate` first (the error names it). Do not `--apply`.
- `action: noop` / `reason: no_drift_detected` → the curated front door is
  healthy and the schema is current; nothing to repair. Offer a plain rebuild
  if the indexes merely look stale.
- `action: dry_run` / `reason: repair_pending` → present the preview from the
  envelope: `data.drifted_regions[]` (e.g. `ROOT-LINKS`), `data.schema_lagging`,
  and the staged proposal path (`data.staged[].path` — e.g.
  `.cogni-wiki/root-index-proposed.md`). That staged root MAP is the
  **content diff surface**: point the user at it so
  they can diff it against the live `wiki/index.md` before committing.

Then, only when the user passed `--apply` (or confirms after the preview):

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/migrate-layout.py" \
  --wiki-root "<wiki_path>" --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS" --repair --apply
```

Report from the envelope: `data.rendered` (the regenerated ROOT-LINKS region) and
`schema_after` (reconciled to the current engine schema when it lagged). A
non-drifted, current-schema base reaches `action: noop`; a second `--apply` is a
clean no-op, so re-running after an interruption is safe.

**OVERVIEW-NARRATIVE drift is an orchestrator step, not a script flag.**
`health.py` emits **two** `structural_drift` classes: an empty ROOT-LINKS span
(script-repairable here) and an OVERVIEW-NARRATIVE block stuck on the bootstrap
placeholder (`_Overview pending — authored on the first knowledge-finalize
run._`). `--repair` resolves the first; it deliberately does **not** touch the
second, because `root_index.py render` carries the OVERVIEW-NARRATIVE block
verbatim and re-authoring real narrative is an LLM task. When health flags the
OVERVIEW-NARRATIVE region, dispatch the `portal-narrator` agent and splice its
output with `overview_update.py narrative-splice --target-file index.md` (the
same path `knowledge-finalize` Step 10.5 sub-step 3.5 / 3.5.1 uses) **before**
the `--repair --apply` call — so the one run lands both the re-authored narrative
and the regenerated ROOT-LINKS, leaving health clean.

### 2d. SCHEMA.md truth-up (all modes, idempotent)

After a rebuild render, a migrate `--apply`, or a repair `--apply` (never on a
dry run), truth-up
the base's self-describing contract. `SCHEMA.md` is not a locked shared-state
file, so this is an orchestrator-side check-then-overwrite, not a
`migrate-layout.py` phase. Detect by the **positive provenance sentinel** the
knowledge-native seed carries in its subtitle — never by grepping for the
generic dir names, which the seed itself mentions in its intentionally-absent
paragraph and would therefore self-match:

```bash
if [ ! -f "<wiki_path>/SCHEMA.md" ]; then echo "missing"
elif grep -qF 'knowledge-native contract (seeded by cogni-knowledge)' "<wiki_path>/SCHEMA.md"; then echo "current"
else echo "generic"; fi
```

- **`generic`** — the base still carries the generic wiki-setup template
  (declaring `decisions/`/`meetings/`/`notes/` the knowledge pipeline never
  writes, omitting `sources/`/`questions/`/`people/`): overwrite
  `<wiki_path>/SCHEMA.md` with the **knowledge-native seed defined in
  `knowledge-setup` Step 3.5 sub-step (b)** — read that heredoc block and
  apply it with this base's title (`binding.json` `knowledge_title`, read in
  Step 1) and today's date (single canonical copy; never fork the seed text
  here, or the two sites drift and the migrate path converges bases onto a
  stale schema).
- **`current`** — the base is already knowledge-native (a hand-extended
  knowledge-native `SCHEMA.md` still carries the sentinel, so user additions
  are never clobbered): clean no-op.
- **`missing`** — report `no-SCHEMA-found` and seed it the same way as
  `generic`.

### 3. Summary

End with a compact block: base title + wiki path, the mode that ran, per-type
render results (or the migration actions), the schema version, and the
SCHEMA.md truth-up outcome (`overwritten` / `already-current` /
`no-SCHEMA-found → seeded`, or `skipped — dry run` when 2d did not run). For a
migrate or repair dry-run, the last line names the apply command so the user can
execute the preview.

## Edge cases

- **Wiki path broken in the binding** — the config read in Step 1.3 surfaces
  it; abort with the error rather than guessing at a wiki root.
- **Partial prior migration** (control files already under `wiki/meta/`, or a
  manual move) — the migrator converges: already-relocated files report
  `skip_already_migrated`, everything else proceeds.
- **Pre-0.0.5 base** — the migrator refuses (`schema_version` predates the
  per-type-dirs layout); route to cogni-wiki's own `migrate_layout.py` first.
- **No themes / empty base** — renders header-only indexes; harmless and
  idempotent.

Wersje

W bazie nie ma innych skilli o nazwie knowledge-index.

Migawka bazy z 13.11.2026 · wersja paczki b001317b8ad0 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100knowledge-setup
    Zakłada bazę cogni-knowledge: wiki oraz manifest binding.json rejestrujący każdy zdeponowany projekt badawczy, a gdy wiki jeszcze nie istnieje, tworzy jej szkielet.
  • 100knowledge-health
    Wykonuje strukturalną kontrolę kondycji bazy cogni-knowledge tylko do odczytu: integralność stron, linków i schematu oraz dryf liczby wpisów i twierdzeń.
  • 100rebuild-skill-index
    Odbudowuje indeks skilli dla platform na danej maszynie, klasyfikując zainstalowane skille według opisu w frontmatterze.
  • 100kb-rebuild-indexes
    Przebudowuje indeks półek bazy wiedzy z wykrywaniem zmian po haszach, ponownie wczytując tylko pliki, które się zmieniły, po dodaniu źródeł lub edycji biblioteki.
  • 100okf-index
    Regeneruje pliki index.md w katalogu knowledge na podstawie frontmatteru pojęć i sprawdza, czy są już nieaktualne.
  • 100building-github-index
    Generuje indeksy z progresywnym ujawnianiem dla repozytoriów GitHub jako wiedzę projektu Claude, w tym przeszukiwalne indeksy blogów technicznych i baz wiedzy oraz łączenie wielu repozytoriów w jeden indeks.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.