custom-claude-skills/skills/distill-best-practices/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
distill-best-practices	Cross-project best practices distillation. Reads changed memory files from all tracked projects and proposes additions, updates, or removals to the skynet/best-practices repo (gitea.oreillyit.nz/skynet/best-practices). Approved changes are committed and pushed to that repo, then synced back to claude-foundations/best-practices/ for backward compatibility. Run from any project -- always targets skynet/best-practices as output. Interactive -- presents proposals for approval before making changes.	Read, Edit, Write, Glob, Grep, Bash(git clone *), Bash(git -C *), Bash(git rev-parse *), Bash(ls *), Bash(cat *), Bash(head *), Bash(date *), Bash(mktemp *), Bash(rm -rf *), Bash(cp *)

Distill Best Practices Skill

You are extracting generalisable best practices from project-specific memory files across all tracked projects.

Pre-gathered context

Pre-gathered context (read at runtime)

The following files should be read using the Read tool at the start of execution:

• ~/dev/claude/projects/claude-foundations/best-practices/.distill-state.json — Distill state (if not found, treat as {})
• ~/dev/claude/projects/claude-foundations/settings.yaml — Settings (if not found, use defaults from instructions)
• Use Glob to list ~/dev/claude/projects/*/ for the projects directory listing

Then clone the skynet/best-practices repo (see Step 0 below) and read from it:

• <tmpdir>/BESTPRACTICES.md — Current best-practices index (from cloned repo)
• Use Glob to list <tmpdir>/*.md for available topic files (from cloned repo)

Instructions

Step 0: Clone skynet/best-practices

Before reading any best-practices content, clone the dedicated repo to a temp directory:

tmpdir=$(mktemp -d)
git clone https://gitea.oreillyit.nz/skynet/best-practices "$tmpdir/best-practices"

The working path for the cloned repo is $tmpdir/best-practices. Use this path throughout — referred to below as <bp-repo>.

Read <bp-repo>/BESTPRACTICES.md and list <bp-repo>/*.md to discover available topic files.

Step 1: Discover changes per project

The project root is ~/dev/claude (hardcoded — change at the top of the !command`` blocks if your layout differs).

Key paths:

• Settings: ~/dev/claude/projects/claude-foundations/settings.yaml
• Best practices repo (primary): <bp-repo>/ (cloned skynet/best-practices)
• Best practices local copy (backward compat): ~/dev/claude/projects/claude-foundations/best-practices/
• Best practices index: <bp-repo>/BESTPRACTICES.md
• Distill state: ~/dev/claude/projects/claude-foundations/best-practices/.distill-state.json

Read settings.yaml (pre-gathered above).

For each project in distill.projects, get its path: ~/dev/claude/<projects_dir>/<project_name>. Also process any distill.extra_projects entries — these have a path field relative to ~/dev/claude.

For each project (from both lists):

1. Get current HEAD: git -C <path> rev-parse HEAD
2. Look up last_sha from .distill-state.json for this project
3. If SHA matches → skip this project (no changes)
4. If last_sha exists → find changed files: git -C <path> diff --name-only <last_sha>..HEAD -- memory/
5. 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 from <bp-repo>/ 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, apply changes to <bp-repo>/:

• ADD: Append the new entry to the target file in <bp-repo>/, matching the existing style (heading level, bullet format, explanation depth)
• UPDATE: Edit the existing entry in place in <bp-repo>/
• REMOVE: Delete the entry from the file in <bp-repo>/

If a new best-practices topic file is needed:

• Create it in <bp-repo>/ following the format of existing files (top-level heading, subheadings per entry, 2-6 lines per entry)
• Add it to <bp-repo>/BESTPRACTICES.md with a one-line description

Sync to local copy for backward compatibility: After applying all changes to <bp-repo>/, copy the modified files to ~/dev/claude/projects/claude-foundations/best-practices/ using cp:

• cp <bp-repo>/BESTPRACTICES.md ~/dev/claude/projects/claude-foundations/BESTPRACTICES.md
• For each modified topic file: cp <bp-repo>/<file>.md ~/dev/claude/projects/claude-foundations/best-practices/<file>.md

Step 6: Commit and push to skynet/best-practices

Stage and commit the changes in the cloned repo, then push:

git -C <bp-repo> add -A
git -C <bp-repo> commit -m "distill: apply best practice updates from project memory

Applied: <count> additions, <count> updates, <count> removals
Sources: <comma-separated list of source projects>"
git -C <bp-repo> push

Report the outcome (commit SHA, push success/failure).

Step 7: Update distill state

Write ~/dev/claude/projects/claude-foundations/best-practices/.distill-state.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 8: Clean up temp directory

Remove the temp directory used for the clone:

rm -rf "$tmpdir"

Step 9: 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
• Commit SHA pushed to skynet/best-practices

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 BESTPRACTICES.md must stay accurate after any file additions
• Proposals are always presented before applying — never auto-apply
• Changes go to skynet/best-practices (primary) and are synced to claude-foundations/best-practices/ (backward compat)