Skip to content
Skills Library
Programming · Automation

knowledge-sync

/knowledge-sync

Use to build the business knowledge base, or align it with code changed outside the kit's flow (hotfix, refactor, another developer), or when reminded it may be behind. Run before committing.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use to build the business knowledge base, or align it with code changed outside the kit's flow (hotfix, refactor, another developer), or when reminded it may be behind. Run before committing.

Arguments

/knowledge-sync [Context[,Context]] [--since <commit>]
Original author description

Use to build the business knowledge base, or align it with code changed outside the kit's flow (hotfix, refactor, another developer), or when reminded it may be behind. Run before committing.

How it works

  1. 1. Scan
  2. 2. Framing — contexts new to the base
  3. 3. Per context
  4. 4. Validation
  5. 5. Apply
  6. 6. Close
Original SKILL.md headings · 74 lines, 1,075 words
SKILL.md preview
---
name: knowledge-sync
description: "Use to build the business knowledge base, or align it with code changed outside the kit's flow (hotfix, refactor, another developer), or when reminded it may be behind. Run before committing."
argument-hint: "[Context[,Context]] [--since <commit>]"
---

# Knowledge sync

Aligns the knowledge base (`knowledge.root` of `.claude/kit.config.json`) with the code. Formats → `references/knowledge-format.md`.

- Nothing reaches the base without the user's confirmation, save the `sync` row of a context nothing touched (§6): it moves the mark, the summary names it. Drafts live in the staging folder `<root>/.sync/`, git-ignored; `cctoolkit knowledge-write` is the one writer of the base — never `Write` or `Edit` under it yourself, the staging excepted.
- No test tag rewritten, no rule sheet or `DESIGN.md` deleted: the base lives beside them until the switch.
- One context at a time, from extraction to `apply`: stopping halfway leaves the finished contexts in the base and nothing half-written.

$ARGUMENTS

Argument: contexts to sync (all when absent), and `--since <commit>`, passed to every scan.

## 1. Scan

`cctoolkit knowledge-scan [--context <C,…>] [--since <commit>]` — one block per context, its mode: `bootstrap` (not in the base), `incremental` (since its sync mark), `full` (in the base, no mark git still knows). Exit 3 → `cctoolkit doctor`, stop. `no context: N handler(s)` → `layout.useCase.contextDepth` or the use-case roots miss them: say so, ask whether to fix `kit.config.json` first or go on without them.

Drafts left by an interrupted sync: `cctoolkit knowledge-write status` prints something other than `nothing staged` → AskUserQuestion: resume them — §4 from its bulk step, the agent's report having gone with its session, then one §5 for every context staged — or discard them (`rm -rf <root>/.sync`, then go on).

Contexts in `bootstrap` mode → §2. The others → §3.

## 2. Framing — contexts new to the base

Show one table: context, handlers (commands, queries), rule sheets and their rules, handlers without a sheet, `DESIGN.md`, prefix (`proposed` when not in `knowledge.contexts`). One AskUserQuestion, two questions:

- **Contexts and prefixes** — "As proposed (Recommended)", "Change a prefix", "Leave contexts out". A change or an exclusion comes through the answer's text. A prefix: 2 to 6 capitals or digits, not `ADR`, unique.
- **Order** — "Smallest first (Recommended)": the first drafts come back fast and show whether the format suits before the large contexts run; "Most rule sheets first"; "Alphabetical".

Add the confirmed prefixes to `knowledge.contexts` in `.claude/kit.config.json`, the existing entries kept. `cctoolkit config validate .` — a `FAIL` on `knowledge` → fix it before going on. Then `cctoolkit knowledge-write init`: it prints the staging path.

## 3. Per context

In the order chosen, bootstrap contexts first, the others after. Each context runs §3 to §5 before the next starts.

**Mechanical first** (incremental): each `rename:` line → `cctoolkit knowledge-write rename <C> <Old> <New>`, each `retire:` line → `cctoolkit knowledge-write retire <C> <Handler>`. No agent for them.

**Nothing left** — no change beyond the mechanical ones (`no agent needed`): skip the agent, go to §5 when something was staged, else keep the context for the final `mark` (§6).

**Over budget** (`OVER BUDGET` in the scan) → AskUserQuestion: "Scan the whole context (Recommended)" — the agent runs on the inventory with the base beside it, mode `full`, scan option `--full`; or "Process the diff as is" — the packet in one agent, its cost above `knowledge.syncBudget`.

**Extraction** — `Agent`, `subagent_type: cctoolkit:knowledge-extractor`, a `description`, prompt:

```
context: <Context> · prefix: <PREFIX> · mode: <bootstrap|incremental|full> · staging: <path>
scan option: <--since <commit> | --full | none>
```

Nothing else: the agent runs the scan itself and reads the format. Sequential, never two at once: the ADR ids are shared and the user may stop between contexts.

Its report ends with `## EXTRACTED — <Context>`, or `## BLOCKED` → show the cause; AskUserQuestion: skip this context (`rm -rf <staging>/<Context>`: its ADRs go with it) or stop the sync.

## 4. Validation

Show one table from the report: `Status` (specified per kind, observed per level), conflicts, `Removed`, `Retire`, the overview's size. Then, in this order:

1. **Conflicts, one question each** — AskUserQuestion, up to four questions per call, one per conflict: the object, what the sheet states, what the code does at `path:line`. Options "The sheet is right" — the code may be a bug: note it for the summary; "The code is right". Either answer edits the staged draft: the observed line deleted, and for the code the rule's title and outcome rewritten to what the code does, its id kept. Left open (an "Other" answer, or no decision) → the object stays `observed`: it goes into `--keep` below.
2. **Removed** — the objects the agent took out of a staged file. One AskUserQuestion, multiSelect, the ones to keep (none selected = remove all): each one kept gets its base text back into the staged file, from the base file.
3. **Retire** — handlers in the base the code no longer has. Confirmed → `cctoolkit knowledge-write retire <C> <Handler>`.
4. **The rest, in bulk** — list the `medium` objects (id, title, source `path:line`), then one AskUserQuestion: "Accept high, keep medium observed, drop low (Recommended)", "Accept high and medium, drop low", "Accept all", "Keep everything observed". Run it as `cctoolkit knowledge-write validate --context <C> --accept <levels> --drop <levels> --keep <open conflicts>` (no `--accept` or `--drop` for "Keep everything observed": nothing to run). A `dangling:` line → remove the citation from the draft that holds it.

An object left `observed` does not block anything: it is in the base, marked, and comes back at the next sync of its context.

## 5. Apply

`cctoolkit knowledge-write status --context <C>`, then AskUserQuestion: "Write <C> to the base (Recommended)" / "Stop here — drafts kept for a later `/cctoolkit:knowledge-sync`". Confirmed → `cctoolkit knowledge-write apply --context <C>`: ids numbered, files written, the `HISTORY.md` row `sync <HEAD>` with its delta, `INDEX.md` rebuilt. `refused:` → fix the draft it names, apply again — a rule `belongs in <Context>/rules.md`: move it there, staged whole, and cite it on the opening line of each use case applying it. `WARN … OVERVIEW.md` → say it; the overview is condensed at the next run of this context or by hand.

Next context → §3.

## 6. Close

Contexts the scan listed and nothing touched → `cctoolkit knowledge-write mark --context <C,…>`: their mark moves on, delta `—`.

Summary: per context, the `HISTORY.md` row written, objects still `observed` per level, conflicts left open, sheets the user declared right against the code (possible bugs, with `path:line`), contexts skipped or stopped. Then the next step: review `git diff -- <root>`, and commit it with the code it describes — a sync committed apart from its code leaves the next sync a window to miss.
Files in this package (2)
  • SKILL.md 7 KB
  • references/knowledge-format.md 13 KB

Versions

RepositoryScoreLicence
This page · pierrebelin/claude-code-toolkit100MIT
agile-4/opem-agent-plugin100MIT

Database snapshot: 13.11.2026 · package version ad1c4d39211e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100qa-knowledge-list
    Browse and search the QA knowledge base. List entries by type, domain, or tag. Show changelog and stats. Use when user says: "list knowledge", "show heuristics", "what's in the knowledge base", "knowledge stats", "show changelog".
  • 100knowledge-ingest
    Ingest or update a codebase in the agent-knowledge base. First run bootstraps the knowledge base from scratch; subsequent runs are incremental (only changed/new/deleted files reprocessed). Uses tree-sitter for zero-token structural extraction. Trigger on "/knowledge-ingest",…
  • 100code-review
    Use when code has been written and needs validation before committing, or when the user asks for a code review or security check.
  • 100knowledge-base
    Read Greptile's synthesized knowledge base for this repository through the Greptile MCP (list_knowledge_bases, list_knowledge_base_documents, get_knowledge_base_document, search_knowledge_base). Use whenever you want context about the codebase, such as how a subsystem or flow…
  • 95knowledge-base-management
    Guide for working with the Knowledge Base system in DEVS. Use this when asked to add knowledge management features, file handling, or document processing.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.