History

Kjell Tore Guttormsen 30edd3f5d8 feat(skill): one generic skill by default, carrying a working method and an answer form The operator built a 2313-concept bundle from one project's own documentation, asked it a question in his own words, and judged the result unusable. The generated skill was an audit contract: all its discipline sat on the accounting -- markings, denominators, budget lines, source pointers -- and none of it on understanding the question, searching again, or writing one coherent answer. Two sentences actively forbade the second of those. The two forbidding sentences are gone and their replacements are tested from both sides. "Do not go looking for context the pre-pass deliberately withheld" read as "one run per question", and no wording of the operator's question put the right document inside a single run's cut -- so a rule against a second run was a rule against finding it at all. "Not something to retry with a narrower question" generalised a budget-refusal case into the same ban. SS 2.2 of the contract said the first of them, so the contract moved with the skill rather than being left to disagree with it: a second pre-pass run with other terms, and a fetch of a concept the payload NAMED, are reachable; SS 9's two real boundaries -- directory enumeration, the verdict layer -- are not. Two new sections, and the checker requires them. `## Working method`: read the bundle's map, put the question into the bundle's own words, split a broad question into 2-4 sub-questions, search per sub-question, read what lay just outside the cut and search again with its words, same method across several bundles, then assemble ONE answer ordered by sub-question, saying which source holds and what is not covered. `## Answer form`: the questioner's language, plain prose, no `below_k`, no digests, no budget lines, no denominators; short textbook-style references (document + section, plus bundle where several were read); and the audit trail written only when the questioner asks for it or into a document that travels without the skill. `REQUIRED_SECTIONS` follows the template and the contract's new SS 2.5 and SS 2.6 -- never the other way round. The generic skill becomes what `okf skill` and `okf project` write. A per-bundle skill's numbers go stale the moment its bundle is rebuilt, one copy per consuming project, and a project with two bundles installs two near-identical skills; the generic form carries no bundle's numbers and names `okf card` for them. `--for-bundle` is the opt-in for the instantiated copy, which still refuses out loud on a stale pairing -- safe to keep, not enough to keep default. `rule_bundle_identity` learned to tell a generic skill from an unfilled template by the frontmatter name the generator writes, so the template still fails for the opposite reason: it declares no identity because it is unfinished. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-09-20 23:53:34 +02:00
..
example-payload.json	feat(skill): one generic skill by default, carrying a working method and an answer form	2026-09-20 23:53:34 +02:00
README.md	feat(consume): parent reaches the reader -- excerpt field, body link, checker rule	2026-09-11 12:36:23 +02:00

Kjell Tore Guttormsen 30edd3f5d8 feat(skill): one generic skill by default, carrying a working method and an answer form

The operator built a 2313-concept bundle from one project's own documentation,
asked it a question in his own words, and judged the result unusable. The
generated skill was an audit contract: all its discipline sat on the accounting
-- markings, denominators, budget lines, source pointers -- and none of it on
understanding the question, searching again, or writing one coherent answer.
Two sentences actively forbade the second of those.

**The two forbidding sentences are gone and their replacements are tested from
both sides.** "Do not go looking for context the pre-pass deliberately
withheld" read as "one run per question", and no wording of the operator's
question put the right document inside a single run's cut -- so a rule against
a second run was a rule against finding it at all. "Not something to retry with
a narrower question" generalised a budget-refusal case into the same ban.
SS 2.2 of the contract said the first of them, so the contract moved with the
skill rather than being left to disagree with it: a second pre-pass run with
other terms, and a fetch of a concept the payload NAMED, are reachable; SS 9's
two real boundaries -- directory enumeration, the verdict layer -- are not.

**Two new sections, and the checker requires them.** `## Working method`: read
the bundle's map, put the question into the bundle's own words, split a broad
question into 2-4 sub-questions, search per sub-question, read what lay just
outside the cut and search again with its words, same method across several
bundles, then assemble ONE answer ordered by sub-question, saying which source
holds and what is not covered. `## Answer form`: the questioner's language,
plain prose, no `below_k`, no digests, no budget lines, no denominators; short
textbook-style references (document + section, plus bundle where several were
read); and the audit trail written only when the questioner asks for it or
into a document that travels without the skill. `REQUIRED_SECTIONS` follows the
template and the contract's new SS 2.5 and SS 2.6 -- never the other way round.

**The generic skill becomes what `okf skill` and `okf project` write.** A
per-bundle skill's numbers go stale the moment its bundle is rebuilt, one copy
per consuming project, and a project with two bundles installs two
near-identical skills; the generic form carries no bundle's numbers and names
`okf card` for them. `--for-bundle` is the opt-in for the instantiated copy,
which still refuses out loud on a stale pairing -- safe to keep, not enough to
keep default. `rule_bundle_identity` learned to tell a generic skill from an
unfilled template by the frontmatter name the generator writes, so the template
still fails for the opposite reason: it declares no identity because it is
unfinished.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-20 23:53:34 +02:00

example-payload.json

feat(skill): one generic skill by default, carrying a working method and an answer form

2026-09-20 23:53:34 +02:00

README.md

feat(consume): parent reaches the reader -- excerpt field, body link, checker rule

2026-09-11 12:36:23 +02:00

README.md

References

example-payload.json is a real payload, not an illustration, and ../SKILL.md is the skill generated for the same bundle. Both come from the three-concept golden bundle that ships in this repository, examples/ingest-golden-segmented-okf-v0-2/expected-bundle, so anyone reading this file can regenerate them byte for byte and compare. Neither carries content from any corpus.

Regenerate them from the repository root rather than editing either file, with okf being this checkout's own install (for example .venv/bin/okf):

okf skill examples/ingest-golden-segmented-okf-v0-2/expected-bundle \
  --out skills/okf-consume --force --example-question "Hva sier veiledningen om krav?"
python3 -c 'import os, pathlib; p = pathlib.Path("skills/okf-consume/SKILL.md"); p.write_text(p.read_text(encoding="utf-8").replace(os.path.realpath(".") + "/", ""), encoding="utf-8")'
okf check --skill skills/okf-consume/SKILL.md \
  --payload skills/okf-consume/references/example-payload.json

Why each part is there:

--force: the generator refuses to replace an existing SKILL.md (refused (target_occupied)), because a silent overwrite would destroy a hand-edited copy.
--example-question: without it the question is derived from the bundle's own titles and the payload is a different one. tests/test_okf_consume.py asserts this payload byte for byte against the pre-pass for exactly Hva sier veiledningen om krav?, so the question is part of what the file is.
The python3 line: okf skill writes the bundle root and the skill's own path absolute when --out is not under .claude/skills/, and this directory is not. Shipped as generated, the two commands in SKILL.md would name one checkout on one machine. The line strips that checkout's prefix and nothing else, and a test holds the shipped SKILL.md to the generator's output with exactly that prefix removed.
okf check should report conformant: 17 rules over 3 excerpts and 0 withheld entries, 0 findings and exit 0.

The generated name is b-golden-segmented-okf-v0-2-consume while this directory stays skills/okf-consume/. Claude Code takes a project or personal skill's command from its directory name and uses name as a display label, so a copy placed at .claude/skills/okf-consume/ is still /okf-consume.

The payload is here so that its shape can be read without running anything, and so that a reader can see what the members the contract does not name look like in practice: text and text_sha256 on every excerpt (§ 8 permits additional members; § 1 defines an excerpt as delivered content, and without a body the budget gate would measure a skeleton), rank, bundle_id_inherited, and the raw_bytes/encoding_delta pair that gives the known-positive a second, independent check.