Chemenu 2.1.0 - deterministischer Wissenskompiler
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
This commit is contained in:
+160
@@ -0,0 +1,160 @@
|
||||
# Conversation Transcript - AGENTS.md Skill Restructuring Session
|
||||
|
||||
> Source: GitHub Copilot chat session (Claude Sonnet 5), this workspace
|
||||
> Collected: 2026-08-04
|
||||
> Participant: Torben
|
||||
|
||||
Faithful summary transcript of a single chat session covering: analysis of whether to split
|
||||
`AGENTS.md` into discrete agent skills, fact-checking of a pasted "instruction set" proposing a
|
||||
concrete cross-platform restructuring, and the resulting implementation.
|
||||
|
||||
---
|
||||
|
||||
## Turn 1 - Query: should AGENTS.md become a number of skills like Farza's gist?
|
||||
|
||||
User asked whether transforming `AGENTS.md` into several skills (as popularized by Farza's
|
||||
personal-wiki gist) would create more specificity and less context impact, referencing prior
|
||||
ingested sources ("LLM Improvements Sonnet/Codex Analysis").
|
||||
|
||||
Assistant research and findings:
|
||||
- Farza's gist (`gist.github.com/farzaa/c35ac0cfbeb957788650e36aabea836d`) is actually **one**
|
||||
skill file (`name: wiki`) with an `argument-hint` dispatching sub-commands
|
||||
(`ingest|absorb|query|cleanup|breakdown|status`) - not several independently-discovered skills.
|
||||
A community comment by "pascalandy" in the same gist proposes a separate, unrelated "Wiki
|
||||
Schema (Global)" with its own tag taxonomy (`area/kind/topic/status/pty`) and hard rules
|
||||
(page split >200 lines, INDEX scaling >50 entries/200 pages, mass-update confirmation gate at
|
||||
10+ pages, Session Orientation Protocol).
|
||||
- VS Code's own bundled Copilot documentation (via the `agent-customization` skill,
|
||||
`references/skills.md`) confirms a **true multi-skill, progressive-disclosure mechanism**:
|
||||
`SKILL.md` files under `.github/skills/<name>/`, `.agents/skills/<name>/`, or
|
||||
`.claude/skills/<name>/` (project scope), discovered in 3 tiers - Discovery (~100 tokens:
|
||||
name+description) -> Instructions (<5000 tokens: body loads only when relevant) -> Resources
|
||||
(loaded only if referenced).
|
||||
- The root `AGENTS.md` in this repo was measured at **745 lines**, attached in full on every
|
||||
chat turn regardless of task (confirmed by grep of `^#{1,3} ` headings and `^## Version
|
||||
History` line number). VS Code's own `agent-instructions.md` reference explicitly calls a
|
||||
kitchen-sink AGENTS.md an anti-pattern ("Minimal by default: only what's relevant to *every*
|
||||
task").
|
||||
- Conclusion: a **true multi-skill split** (Option C: thin always-on core + one skill per
|
||||
workflow + shared reference files) would meaningfully cut always-resident context and sharpen
|
||||
per-workflow specificity, more so than Farza's literal one-skill design (which buys nothing in
|
||||
a repo that is entirely a wiki, since almost every session touches it).
|
||||
|
||||
---
|
||||
|
||||
## Turn 2 - "How is the situation with Claude Code, Mistral Vibe? Do they understand such skill separation too?"
|
||||
|
||||
Assistant began fetching primary docs for Claude Code (`code.claude.com/docs/en/skills`) and
|
||||
searched for "Mistral Vibe" (initial attempts to guess a marketing URL 404'd) before the user
|
||||
interrupted with a pasted "web search result, synthesized" instruction set (Turn 3).
|
||||
|
||||
---
|
||||
|
||||
## Turn 3 - User pastes a synthesized "Instruction Set: Restructure AGENTS.md into Cross-Platform Agent Skills" and asks for a plan
|
||||
|
||||
The pasted document claimed:
|
||||
1. Token economics: "a full ingest costs roughly 5-8x the source token count"; a documented
|
||||
"RTFM / retrieval-layer approach" cut token usage by 61% and improved resolve rate from
|
||||
~55-64% to 100% on an 8,260-file corpus.
|
||||
2. Precedents: `kfchou/wiki-skills` (6 Claude Code skills: wiki-init/ingest/query/lint/update/
|
||||
audit/merge), `vanillaflava/llm-wiki-skills` (6 skills, cross-platform installer), Farza's
|
||||
gist (single-file precedent), `yugasun/llm-wiki-skills` (single skill, Chinese-language,
|
||||
sync-mirror-verify script pattern).
|
||||
3. Target layout: `.agents/skills/wiki-{ingest,query,lint,create,update}/SKILL.md` as canonical,
|
||||
with per-tool wiring: Claude Code via `~/.claude/skills/` symlink, Codex CLI via
|
||||
`~/.codex/skills/` symlink, Mistral Vibe reads `.agents/skills/` natively (no action), GitHub
|
||||
Copilot via a new `.vscode/settings.json` `chat.agentSkillsLocations` setting.
|
||||
4. Retain-in-root vs move-to-skills split for AGENTS.md content, and an execution checklist.
|
||||
|
||||
**Assistant fact-checked every concrete claim against primary sources before planning**, per this
|
||||
repo's own "no confident answer without a source" rule:
|
||||
|
||||
- **Confirmed correct:** `kfchou/wiki-skills` and `vanillaflava/llm-wiki-skills` are real
|
||||
repositories (verified via `github_text_search`/`github_repo`) implementing this pattern with
|
||||
5-6 discrete skills each. `yugasun/llm-wiki-skills` is real too - single skill, Chinese-
|
||||
language, demonstrating a canonical-source + `sync-skill-layout.sh`/`verify-skill-layout.sh`
|
||||
mirroring pattern into `.github/skills/`, `.agents/skills/`, `.claude-plugin/`.
|
||||
- **Confirmed correct:** Mistral Vibe (`github.com/mistralai/mistral-vibe`, listed on
|
||||
`agentskills.io`'s client showcase as "a command-line coding assistant powered by Mistral's
|
||||
models") natively reads `.vibe/skills/` and **`.agents/skills/`** (project, trusted-folder-
|
||||
gated) plus `~/.vibe/skills/`/`~/.agents/skills/` (user) - confirmed directly in
|
||||
`mistralai/mistral-vibe`'s source (`vibe/core/skills/builtins/skill_creator.py`,
|
||||
`vibe/core/skills/builtins/vibe.py`, `CHANGELOG.md`: "Load skills from `~/.agents/skills` so
|
||||
they can be shared across agents").
|
||||
- **Confirmed correct:** Claude Code only reads `.claude/skills/<name>/SKILL.md` (project) or
|
||||
`~/.claude/skills/` (personal/plugin) per official docs (`code.claude.com/docs/en/skills`) -
|
||||
it does **not** read `.agents/skills/` natively, so a mirror/symlink really is required.
|
||||
- **CORRECTED - Codex CLI:** the pasted claim of `~/.codex/skills/` + symlink is **wrong**.
|
||||
OpenAI's own docs (`learn.chatgpt.com/docs/build-skills`, "Where Codex loads local skills")
|
||||
confirm Codex natively scans **`.agents/skills`** from the current working directory up to the
|
||||
repository root, plus `$HOME/.agents/skills` - no symlink needed at all.
|
||||
- **CORRECTED/FLAGGED - GitHub Copilot:** VS Code's own bundled skill docs say `.agents/skills/`
|
||||
is a native project-scope location, no settings.json required - conflicting with the pasted
|
||||
claim that `chat.agentSkillsLocations` must be configured. `vanillaflava/llm-wiki-skills`'s own
|
||||
README repeats the `chat.agentSkillsLocations` claim too, so it isn't fabricated, but may be
|
||||
stale for the currently-installed Copilot Chat version. Flagged as needing an empirical check
|
||||
rather than asserted either way.
|
||||
- **NOT verified / explicitly flagged as unsourced, not to be repeated as fact:** the "5-8x"
|
||||
token-cost multiplier and the "61% reduction / 100% resolve rate on an 8,260-file corpus"
|
||||
statistic, and "Leo Alexandru's production setup" - no source found for any of the three; the
|
||||
assistant explicitly told the user these would not be carried into the plan as facts.
|
||||
|
||||
**Net conclusion:** `.agents/skills/` is a better canonical choice than the pasted plan assumed -
|
||||
3 of 4 target tools (Copilot, Codex, Mistral Vibe) read it natively with zero extra wiring; only
|
||||
Claude Code needs a generated mirror.
|
||||
|
||||
The assistant then asked three clarifying questions before finalizing the plan:
|
||||
1. How to handle the conflicting Copilot `chat.agentSkillsLocations` evidence -> user chose
|
||||
**"Test first"** (empirical check before assuming either way).
|
||||
2. How to keep `.claude/skills/` in sync with `.agents/skills/` -> user chose **"new wikitool
|
||||
subcommand"** (`tools/wikitool skills sync`/`verify`) over a standalone script or a one-off
|
||||
manual symlink.
|
||||
3. Whether the skill set should map 1:1 to the 5 existing AGENTS.md workflows, merge
|
||||
create+update, and/or add a 6th read-only status skill -> user chose **both**: merge
|
||||
create+update into one `wiki-manage` skill AND add a new `wiki-status` skill, netting 5 total
|
||||
skills: `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-manage`, `wiki-status`.
|
||||
|
||||
A detailed plan was written to `/memories/session/plan.md` and presented to the user.
|
||||
|
||||
---
|
||||
|
||||
## Turn 4 - "start implementation"
|
||||
|
||||
The assistant implemented the plan:
|
||||
|
||||
1. **Phase 0 (empirical check):** created a throwaway `.agents/skills/probe/SKILL.md`, later
|
||||
deleted after use; the fresh-session discovery result could not be conclusively observed
|
||||
within the same turn (no new skill-listing update surfaced before deletion) - left as an open
|
||||
follow-up.
|
||||
2. **Phase 1:** wrote the 5 skill files verbatim-extracted from AGENTS.md's INGEST/QUERY/LINT
|
||||
workflows (`wiki-ingest`, `wiki-query`, `wiki-lint`), a merged CREATE+UPDATE
|
||||
(`wiki-manage`, two labeled procedures), and a new read-only `wiki-status` skill built on
|
||||
existing `wikitool lint`/`sources coverage` read paths (no new CLI logic).
|
||||
3. **Phase 2:** slimmed root `AGENTS.md` from 745 to ~573 lines - replaced the 5 full workflow
|
||||
sections with a compact "## Skills" pointer table, trimmed "## Git Automation" to policy-only
|
||||
(moved the per-workflow "when does this publish" detail into each skill's Output section),
|
||||
added a new Version History row.
|
||||
4. **Phase 3:** added `tools/wiki_tools/commands/skills_sync.py` (`sync` copies
|
||||
`.agents/skills/*` into `.claude/skills/*`; `verify` checks frontmatter `name`/`description`,
|
||||
mirror staleness, and that AGENTS.md's Skills table still references every skill), registered
|
||||
via `app.add_typer(skills_sync.app, name="skills")` in `cli.py`, following the exact pattern
|
||||
of the existing `xref`/`new_page`/`provenance_cmd` command modules.
|
||||
5. **Phase 4 (verification):** `tools/wikitool skills sync` then `tools/wikitool skills verify`
|
||||
passed clean (5 skills, canonical/mirrored/referenced). `tools/wikitool lint` ran across 236
|
||||
pages and surfaced **pre-existing, unrelated** issues (duplicate titles / broken links among
|
||||
`wiki/entities/projects/{kfchou,vanillaflava,yugasun}/...`, originating from an earlier ingest
|
||||
of a page called "Source - Copilot Skill Restructure Instructions") - confirmed via
|
||||
`git status --porcelain` that those files were already committed and untouched by this
|
||||
session, so left alone as out of scope. `pytest` (tools/) passed 46/46. Published via
|
||||
`tools/wikitool publish` at commit `ae2024d`.
|
||||
|
||||
**Noteworthy side-finding during this session:** the wiki already contained a source page,
|
||||
"Source - Copilot Skill Restructure Instructions", plus derived entity/concept pages
|
||||
(`Codex CLI`, `Mistral Vibe`, `GitHub Copilot`, `Cross-platform Agent Skills`, `Token Economics`,
|
||||
`Scale Ceiling`, `Workflow Extraction`, `Context Isolation`, `kfchou/wiki-skills`,
|
||||
`vanillaflava/llm-wiki-skills`, `yugasun/llm-wiki-skills`, `llm-wiki-test1`) - created from an
|
||||
earlier, unverified ingest of the exact same pasted instruction set discussed in Turn 3, **before**
|
||||
this session's fact-checking happened. Several of those pages repeat claims this session
|
||||
specifically found unverified (the "5-8x"/"61%/100%" statistics in `Token Economics.md`) or
|
||||
factually wrong (`Codex CLI.md`'s `~/.codex/skills/` + symlink claim). This source/ingest is
|
||||
filed specifically to supersede those points with the verified facts above.
|
||||
Reference in New Issue
Block a user