Add three knowledge distillation skills: /log, /reflect-logs, /distill-best-practices
- /log: end-of-session capture of decisions, gotchas, open questions to memory/log/ - /reflect-logs: processes session logs into topic memory files with staleness detection - /distill-best-practices: cross-project best practices extraction with interactive proposals - README.md: updated skill table with all three new skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
145
skills/distill-best-practices/SKILL.md
Normal file
145
skills/distill-best-practices/SKILL.md
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: distill-best-practices
|
||||
description: >
|
||||
Cross-project best practices distillation. Reads changed memory files from all tracked
|
||||
projects and proposes additions, updates, or removals to claude-foundations/best-practices/.
|
||||
Run from any project — always targets claude-foundations as output. Interactive — presents
|
||||
proposals for approval before making changes.
|
||||
allowed-tools: Read, Edit, Write, Glob, Grep, Bash(git -C *), Bash(git rev-parse *), Bash(ls *), Bash(cat *), Bash(head *), Bash(date *)
|
||||
---
|
||||
|
||||
# Distill Best Practices Skill
|
||||
|
||||
You are extracting generalisable best practices from project-specific memory files across all tracked projects.
|
||||
|
||||
## Pre-gathered context
|
||||
|
||||
### Distill state
|
||||
!`cat ~/dev/claude/projects/claude-foundations/best-practices/.distill-state.json 2>/dev/null || echo "{}"`
|
||||
|
||||
### Settings
|
||||
!`cat ~/dev/claude/projects/claude-foundations/settings.yaml 2>/dev/null || echo "No settings file found"`
|
||||
|
||||
### Current best-practices index
|
||||
!`cat ~/dev/claude/projects/claude-foundations/best-practices/INDEX.md 2>/dev/null || echo "No index found"`
|
||||
|
||||
### Available best-practices files
|
||||
!`ls -1 ~/dev/claude/projects/claude-foundations/best-practices/ 2>/dev/null || echo "No best-practices directory"`
|
||||
|
||||
### Projects directory listing
|
||||
!`ls -1d ~/dev/claude/projects/*/ 2>/dev/null || echo "No projects directory"`
|
||||
|
||||
## Instructions
|
||||
|
||||
### Step 1: Discover changes per project
|
||||
|
||||
Read `settings.yaml` for the list of tracked projects and `projects_dir`.
|
||||
|
||||
For each project in `distill.projects`:
|
||||
|
||||
1. Get the project path: `<projects_dir>/<project_name>`
|
||||
2. Get current HEAD: `git -C <path> rev-parse HEAD`
|
||||
3. Look up `last_sha` from `.distill-state.json` for this project
|
||||
4. If SHA matches → skip this project (no changes)
|
||||
5. If `last_sha` exists → find changed files: `git -C <path> diff --name-only <last_sha>..HEAD -- memory/`
|
||||
6. If `last_sha` is missing (first run) → list all memory files: `ls <path>/memory/*.md`
|
||||
|
||||
Filter to only `memory/*.md` files (exclude `memory/log/` — those are raw, unprocessed).
|
||||
|
||||
If no projects have changes, say so and stop.
|
||||
|
||||
### Step 2: Read changed memory files
|
||||
|
||||
For each changed memory file, read its full content using the Read tool.
|
||||
|
||||
Also identify which existing best-practices topic files cover the same domain. Use this mapping as a guide:
|
||||
- `gotchas-k8s.md` → `kubernetes.md`
|
||||
- `gotchas-cilium.md` → `kubernetes.md`
|
||||
- `gotchas-helm.md` → `helm.md`
|
||||
- `gotchas-ansible.md` → `ansible.md`
|
||||
- `gotchas-sops.md` → `secrets-management.md`
|
||||
- `process-lessons.md` → `validation.md`, `debugging.md`
|
||||
- `decisions.md` → various (match by content)
|
||||
- Other gotchas → match by topic or propose a new file
|
||||
|
||||
Read the matching best-practices files so you can compare.
|
||||
|
||||
### Step 3: Analyse and propose
|
||||
|
||||
For each potential change, classify it:
|
||||
|
||||
- **ADD**: A lesson that is project-agnostic and valuable across projects. When generalising:
|
||||
- Strip project-specific details (IPs, namespace names, service names, hostnames)
|
||||
- Replace specifics with generic descriptions (e.g., "10.111.0.5" → "the DNS server IP")
|
||||
- Keep the principle and the reasoning — lose the implementation detail
|
||||
- Only promote lessons that would apply to at least one other project type
|
||||
|
||||
- **UPDATE**: An existing best-practice entry that has new supporting evidence, needs refinement, or should be expanded with a new example.
|
||||
|
||||
- **REMOVE**: A best-practice that has been invalidated — version-specific bug fixed, tool changed, approach superseded. Cross-reference: if the source gotcha was removed from the project's memory, the best-practice may be stale.
|
||||
|
||||
### Step 4: Present proposals
|
||||
|
||||
**Do NOT make any changes yet.** Present a numbered list of proposals:
|
||||
|
||||
```
|
||||
Proposals:
|
||||
|
||||
1. ADD to kubernetes.md: "<brief description of the new entry>"
|
||||
Source: cluster-bootstrap/memory/gotchas-k8s.md
|
||||
|
||||
2. UPDATE validation.md: "<what changes and why>"
|
||||
Source: cluster-bootstrap/memory/process-lessons.md
|
||||
|
||||
3. REMOVE helm.md: "<entry to remove and why it's stale>"
|
||||
Reason: Source gotcha removed in cluster-bootstrap commit abc1234
|
||||
```
|
||||
|
||||
Wait for the user to approve, modify, or reject proposals. The user may say "all", give specific numbers, or ask for changes.
|
||||
|
||||
### Step 5: Apply approved changes
|
||||
|
||||
For each approved proposal:
|
||||
- **ADD**: Append the new entry to the target file, matching the existing style (heading level, bullet format, explanation depth)
|
||||
- **UPDATE**: Edit the existing entry in place
|
||||
- **REMOVE**: Delete the entry from the file
|
||||
|
||||
If a new best-practices topic file is needed:
|
||||
- Create it following the format of existing files (top-level heading, subheadings per entry, 2-6 lines per entry)
|
||||
- Add it to `INDEX.md` with a one-line description
|
||||
|
||||
### Step 6: Update distill state
|
||||
|
||||
Write `best-practices/.distill-state.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"last_run": "<ISO-8601 timestamp>",
|
||||
"projects": {
|
||||
"<project_name>": {
|
||||
"path": "<absolute_path>",
|
||||
"last_sha": "<current HEAD sha>",
|
||||
"last_run": "<ISO-8601 timestamp>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Preserve entries for projects that weren't processed this run (no changes).
|
||||
|
||||
### Step 7: Summary
|
||||
|
||||
Print:
|
||||
- Projects scanned and number of changed memory files per project
|
||||
- Number of proposals (add/update/remove)
|
||||
- Number approved and applied
|
||||
- Any new best-practices files created
|
||||
|
||||
## Quality checks
|
||||
|
||||
- Best practices must be **project-agnostic** — no hardcoded IPs, namespaces, or service names
|
||||
- Each entry should include the **principle and reasoning**, not just the rule
|
||||
- Entries must be **deduplicated** against existing best-practices content
|
||||
- The **INDEX.md** must stay accurate after any file additions
|
||||
- Proposals are **always presented before applying** — never auto-apply
|
||||
Reference in New Issue
Block a user