skills/distill-best-practices/SKILL.md

@@ -2,10 +2,12 @@
 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
+  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.
-allowed-tools: Read, Edit, Write, Glob, Grep, Bash(git -C *), Bash(git rev-parse *), Bash(ls *), Bash(cat *), Bash(head *), Bash(date *)
+allowed-tools: 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
@@ -18,20 +20,36 @@ You are extracting generalisable best practices from project-specific memory fil
 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)
-- `~/dev/claude/projects/claude-foundations/BESTPRACTICES.md` — Current best-practices index
-- Use Glob to list `~/dev/claude/projects/claude-foundations/best-practices/*.md` for available topic files
 - 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 dir**: `~/dev/claude/projects/claude-foundations/best-practices/`
-- **Best practices index**: `~/dev/claude/projects/claude-foundations/BESTPRACTICES.md`
+- **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).
@@ -65,7 +83,7 @@ Also identify which existing best-practices topic files cover the same domain. U
 - `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.
+Read the matching best-practices files from `<bp-repo>/` so you can compare.
 
 ### Step 3: Analyse and propose
 
@@ -102,16 +120,36 @@ Wait for the user to approve, modify, or reject proposals. The user may say "all
 
 ### 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
+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 following the format of existing files (top-level heading, subheadings per entry, 2-6 lines per entry)
-- Add it to `~/dev/claude/projects/claude-foundations/BESTPRACTICES.md` with a one-line description
+- 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
 
-### Step 6: Update distill state
+**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`:
 
@@ -131,13 +169,22 @@ Write `~/dev/claude/projects/claude-foundations/best-practices/.distill-state.js
 
 Preserve entries for projects that weren't processed this run (no changes).
 
-### Step 7: Summary
+### 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
 
@@ -146,3 +193,4 @@ Print:
 - 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)