learning-distill

Estrelas9

Forks2

Atualizado22 de abril de 2026 às 23:46

Read a completed temporary session bundle from `.agents/sessions/` and distill durable repo knowledge into `.agents/` files. Use only after task-closeout has produced a bundle and when the goal is to separate stable guidance from temporary task notes.

Instalação

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Fonte

Hypercubed

Hypercubed/f-flat-minor

Abrir repositório GitHub Ver repositórios do creator

Download

Ocupações relacionadasSOC

Baseado na classificação ocupacional SOC

Desenvolvedores de softwareInformática e Matemática·SOC 15-1252

Explorador de arquivos

9 arquivos

SKILL.md

readonly

Mais deste repositório

mesmo repositório

docs-search

Hypercubed/f-flat-minor

Search `.agents/` durable knowledge using a local JSON index generated from markdown sources. Use `index-docs.py` to refresh search data, and optionally run docs-compile when you also want durable section index files regenerated.

2026-05-259

docs-compile

Hypercubed/f-flat-minor

Regenerate optional durable docs indexes and rebuild docs-search cache from local markdown sources. Use after editing `.agents/docs/` (any section), and before maintenance passes that validate index alignment.

2026-04-229

knowledge-lint

Hypercubed/f-flat-minor

Check the `.agents/` knowledge layer for duplication, contradiction, staleness, oversized guidance, broken or stale links, missing index coverage, uncategorized or misplaced knowledge, and consistency between `decisions/` and `troubleshooting/` indexes and their entry files. Use as a periodic maintenance pass.

2026-04-229

plans

Hypercubed/f-flat-minor

Use whenever working with maintainer plans under .agents/docs/plans/. Covers reading a plan before implementation, creating or scaffolding a plan, and updating status or body during or after work. Trigger when the user asks to plan, scope deferred work, check what is planned, or record a plan. Also trigger at the start of implementation to see whether a plan already exists.

2026-04-229

task-closeout

Hypercubed/f-flat-minor

Capture the current task into a structured temporary session bundle under `.agents/sessions/` so a learning agent can later distill durable repo knowledge. Use for completed, blocked, or abandoned tasks with meaningful changes, debugging, validation, or reusable lessons.

2026-04-229

write-plan

Hypercubed/f-flat-minor

Scaffold a new maintainer plan under `.agents/docs/plans/<id>.md` with valid YAML frontmatter, collision-checked ids, optional body stub sections (link decisions in a

2026-04-229

name	learning-distill
description	Read a completed temporary session bundle from `.agents/sessions/` and distill durable repo knowledge into `.agents/` files. Use only after task-closeout has produced a bundle and when the goal is to separate stable guidance from temporary task notes.

Learning Distill

Goal

Convert raw task evidence into concise, durable repo knowledge.

Inputs

session bundle directory under .agents/sessions/
.agents/AGENTS.md
.agents/docs/MAINTENANCE.md
.agents/docs/index.md
.agents/docs/log.md
.agents/docs/decisions/ (per-decision markdown files; see index.md there)
.agents/docs/troubleshooting/ (per-pattern markdown files; see index.md there)
.agents/playbooks/

Read the canonical task/session identifier from the task_id field in the bundle's summary.json. Do not infer identity from the session folder name.

Skill initialization (before first distillation)

Run this once per target repo after the skill files are present under .agents/skills/learning-distill/ (for example after copying only that skill folder or after an npx/package install drops it there). Idempotent: safe to repeat.

Resolve the repo root (the directory that contains .git/ in normal layouts).
Ensure .agents/ exists.
Ensure .agents/playbooks/ exists. If .agents/playbooks/README.md is missing, copy bootstrap/playbooks/README.md from this skill folder into place.
Ensure .agents/docs/ exists. For each of index.md, MAINTENANCE.md, and log.md, if the file is missing under .agents/docs/, copy it from bootstrap/docs/ in this skill folder. If .agents/docs/decisions/index.md or .agents/docs/troubleshooting/index.md is missing, copy the entire contents of bootstrap/docs/decisions/ and bootstrap/docs/troubleshooting/ respectively, creating only files that do not already exist (do not overwrite). If a file already exists, do not overwrite it.
Ensure .agents/sessions/ exists. If .agents/sessions/README.md is missing, copy bootstrap/sessions/README.md from this skill folder into place.
If .agents/AGENTS.md is missing, copy bootstrap/AGENTS.md from this skill folder into place. If it already exists, do not overwrite it.
Ensure .agents/.gitignore exists. If it is missing, create it with exactly:
```
sessions/*
!sessions/README.md
```
If .agents/.gitignore already exists, merge these two lines if they are absent; do not remove unrelated ignore rules.
If the repo does not track .agents/.gitignore and the user relies on the repo root .gitignore, ensure equivalent patterns exist there: .agents/sessions/* and !.agents/sessions/README.md.

This initialization supplies the durable doc scaffold the distill procedure expects. It does not fabricate repo-specific guidance beyond the kit templates. The same bootstrap/ tree is the canonical source for knowledge-lint initialization when both skills are installed (see that skill’s SKILL.md).

Classification categories

Classify each candidate lesson as one of:

ephemeral
AGENTS guidance
troubleshooting
repo decision
playbook

Distillation rules

Preserve only stable, reusable knowledge.
Do not copy task history into .agents/AGENTS.md.
Add or edit a file under .agents/docs/decisions/ for rationale and nuance (filename stem and frontmatter id must match; update decisions/index.md when adding a new decision). Collision checks are only within decisions/. Use decisions/<slug> or troubleshooting/<slug> in depends_on (see Entry id and qualified graph references in MAINTENANCE.md).
Add or edit a file under .agents/docs/troubleshooting/ for recurring failures and fixes (same id/filename rules; check collisions only within troubleshooting/).
After changing durable entry files, run bash .agents/skills/docs-compile/scripts/docs-compile.sh when the optional docs-compile skill is installed to regenerate decisions/index.md, troubleshooting/index.md, and docs-search cache (see .agents/skills/docs-compile/SKILL.md) before knowledge-lint or publishing.
If docs-compile is not installed, continue distillation and regenerate search cache with python3 .agents/skills/docs-search/scripts/index-docs.py when available. This end-of-run index-docs.py is separate from the pre-distillation search refresh in the Procedure (step 2a): one invocation seeds search before you read and compare; the other refreshes the index after writes.
Use .agents/playbooks/ for durable multi-step procedures.
Add to .agents/AGENTS.md only if the lesson is broad, stable, concise, and actionable.
Reject low-confidence or one-off lessons.
Keep .agents/docs/log.md minimal: no secrets, personal data, private business details, long raw outputs, or copied transcript text.

Finding session bundles (gitignore)

By kit design, per-task folders under .agents/sessions/ are gitignored (only README.md is meant to stay tracked). Many search and listing tools skip gitignored paths by default, so a first pass can look empty even when bundles exist on disk.

Do not conclude that .agents/sessions/ has no bundles based only on an ignore-aware code search or glob.

Do locate bundles with at least one method that actually sees ignored files, for example:

List the directory with a filesystem API or shell (ls, find, and similar) rather than relying solely on an IDE index that excludes gitignored paths.
When using ripgrep, pass flags that include gitignored files (for example --no-ignore-vcs, or --no-ignore if your search is scoped under .agents/sessions/ and you accept searching other ignored paths in that subtree).

Then open each candidate bundle’s summary.json: treat task_id as canonical, and filter or prioritize work using distillation state fields (distilled, status, distillation_status, or equivalents). Do not select a bundle from its folder name alone.

Procedure

Locate the correct session bundle using Finding session bundles (gitignore), then read that bundle’s files.
Read summary.json and use its task_id in notes and log entries. 2a. Search for related existing knowledge. If docs-search is available, refresh the index and search for each candidate lesson topic before comparing files manually:
```
python3 .agents/skills/docs-search/scripts/index-docs.py
python3 .agents/skills/docs-search/scripts/search-docs.py "<lesson topic>"
```
Open any returned file paths and treat them as the primary input to step 3 (Compare) and step 4 (Remove duplication). This avoids loading the entire .agents/ tree into context.
Compare candidates against the existing .agents/ files.
Remove duplication.
Classify each lesson.
Draft minimal updates to the appropriate file or files.
Update .agents/docs/index.md if durable knowledge structure changed.
Append a concise, non-sensitive entry to .agents/docs/log.md (distillation is the routine workflow that updates this file; see .agents/docs/MAINTENANCE.md Logging policy).
Mark the session bundle as distilled.

Constraints

Do not modify source code.
Do not invent new repo rules unsupported by the task evidence.
Do not expand .agents/AGENTS.md with rationale or narrative.
Do not copy secrets, private identifiers, personal data, customer data, or long raw command/error output into durable docs, especially .agents/docs/log.md.
Prefer small edits over large rewrites.

AGENTS criteria

A lesson belongs in .agents/AGENTS.md only if it is:

high confidence
broadly useful in this repo
likely to recur
concise
actionable