SuperAPI AI Directory

sync-pocock-skills

General & other

View repository

Updated 10-17 10:19

About this skill

[Historical author source dated 2026-06-18 (UTC). The checked current repository snapshot 9dccb2d0dc06 no longer contains this file path. Current installation and compatibility are unverified.]

Source: https://raw.githubusercontent.com/dmmulroy/.dotfiles/abd74a53e6efc9ef13943f697f6b34719f7684da/home/.pi/agent/skills/sync-pocock-skills/SKILL.md

Sync Pocock Skills

Sync our copies of mattpocock/skills against either the default branch or an exact release, apply pi-specific patches, and surface migration work.

Quick start

Use absolute paths so current-directory confusion does not matter:

SKILL_ROOT="$HOME/.pi/agent/skills/sync-pocock-skills"
bash "$SKILL_ROOT/scripts/sync.sh" \
  "$HOME/.pi/agent/skills" \
  "$SKILL_ROOT/patches" \
  --keep-upstream

For a release, pin its exact tag instead of analysing a moving default branch:

bash "$SKILL_ROOT/scripts/sync.sh" \
  "$HOME/.pi/agent/skills" \
  "$SKILL_ROOT/patches" \
  --ref 'mattpocock-skills@1.0.0' \
  --keep-upstream

Options:

  • --ref <git-ref> — clone an exact tag or branch.
  • --keep-upstream — retain the temporary clone after the script exits.
  • --upstream-dir <dir> — clone into a specific path and retain it.

Workflow

1. Read release notes and analyse

When the user supplies a release URL, read the notes first and pass its tag to --ref. Treat explicit breaking changes as migration instructions, not ordinary file diffs.

Parse these report sections:

  • NEW_SKILLS — upstream skills not installed locally. required_by= marks dependencies of installed skills.
  • LIFECYCLE_CHANGES — installed skills renamed, replaced, removed, or unexpectedly missing upstream.
  • DEPENDENCY_GAPS — model-invoked skills referenced by installed skills but not installed.
  • UPSTREAM_CHANGES — file-level differences in skills that retain the same name.
  • UNPATCHED_PATTERNS — Claude Code or sub-agent references without pi patches.
  • UPSTREAM_DIR — retained upstream skills/ root, requested ref, and resolved commit.

The upstream root contains category directories. Resolve a skill's actual directory before invoking another script:

upstream_root="<UPSTREAM_DIR from sync output>"
skill="<skill-name>"
upstream_skill_dir=$(find "$upstream_root" -mindepth 2 -maxdepth 2 -type d -name "$skill" -print -quit)
[[ -n "$upstream_skill_dir" ]] || { echo "missing upstream skill dir for $skill"; exit 1; }

2. Handle lifecycle changes

Lifecycle mappings live in patches/upstream-migrations.tsv.

  • RENAMED — install the new skill, migrate only still-relevant pi patches or overrides, then remove the old directory and stale configuration.
  • REPLACED — install the replacement as a new skill. Do not blindly port the old instructions or patches.
  • REMOVED — show the release rationale and local diff, then remove the skill and stale patch/override/exclusion entries if the user accepts upstream's removal.
  • MISSING_UPSTREAM — investigate before deleting. Add a migration entry only after confirming the upstream change.

Do not carry disable-model-invocation across a rename or replacement automatically. Upstream 1.0.0 distinguishes:

  • User-invoked skills: disable-model-invocation: true; descriptions are human-facing.
  • Model-invoked skills: no disable flag; descriptions retain auto-invocation triggers.

Respect upstream's classification unless a deliberate pi policy is recorded in patches/local-overrides.json.

3. Resolve dependencies and new skills

Install missing dependencies before updating the skills that invoke them. A user-invoked skill may orchestrate model-invoked skills, but must not invoke another user-invoked skill as an automatic dependency.

For each new optional skill, show its name, category, description, and dependants. Ask whether to:

  • Install — run scripts/install-new.sh.
  • Exclude — append its name to patches/excluded.txt.
bash "$SKILL_ROOT/scripts/install-new.sh" \
  "$skill" "$upstream_skill_dir" \
  "$HOME/.pi/agent/skills" "$SKILL_ROOT/patches"

If installing a router such as ask-matt, first confirm that every skill it routes to is installed. Rerun the analysis after installation to expose any dependency gap.

4. Apply same-name upstream changes

For each CHANGED: entry:

  • changed, no patch — safe to replace from upstream.
  • upstream changed, has patch — inspect the upstream diff, apply, and verify the patch still expresses a pi-specific difference.
  • patch conflict — compare upstream, local, and patch intent; resolve manually and regenerate the patch.
  • new file upstream — copy it.
  • removed upstream — remove it unless it is an intentional local resource.

Apply a complete upstream skill atomically:

bash "$SKILL_ROOT/scripts/apply-upstream.sh" \
  "$skill" "$upstream_skill_dir" \
  "$HOME/.pi/agent/skills" "$SKILL_ROOT/patches"

Inspect the working-tree diff immediately. rsync --delete removes old bundled resources, and local frontmatter not configured in local-overrides.json may disappear.

5. Handle pi-specific patterns

For each UNPATCHED: entry:

  1. Read the file and identify the Claude Code-specific behavior.
  2. Replace it with direct pi instructions.
  3. Regenerate its patch:
bash "$SKILL_ROOT/scripts/make-patch.sh" \
  "$skill" "$rel_path" "$upstream_file" "$our_file" "$SKILL_ROOT/patches"

make-patch.sh uses stable labels. For SKILL.md, it excludes configured local metadata from the text patch while preserving a field if upstream now supplies it natively.

Patch conventions

Claude Code pattern Pi replacement
Agent tool with subagent_type=Explore Walk the codebase using read, grep, find, and bash.
Spawn parallel sub-agents Produce the alternatives independently from the original brief; do not let one alternative anchor the next.
Generic sub-agent / subagent Remove it or replace it with direct-agent instructions.
Check CLAUDE.md first Check AGENTS.md first and CLAUDE.md as fallback.

6. Verify and report

  1. Rerun sync.sh against the same --ref.
  2. Confirm no unexpected lifecycle changes, dependency gaps, upstream changes, or unpatched patterns remain.
  3. Run and read git diff -- <changed skill paths>.
  4. Report skills added, migrated, removed, excluded, and updated; patches created or dropped; unresolved conflicts; and the resolved upstream tag/commit.
  5. Separate metadata-only changes from instruction-body changes. Include short diffs directly; for long diffs include the stat and important hunks.

Configuration

  • patches/excluded.txt — upstream skills intentionally not installed.
  • patches/local-only.txt — local skills that must not be mistaken for removed upstream skills.
  • patches/upstream-migrations.tsv — confirmed rename, replacement, and removal mappings.
  • patches/local-overrides.json — deliberate pi frontmatter policy applied after upstream and text patches.
  • patches/*.patch — pi-specific content changes.

File layout

sync-pocock-skills/
├── SKILL.md
├── scripts/
│   ├── sync.sh
│   ├── apply-upstream.sh
│   ├── install-new.sh
│   ├── apply-frontmatter-overrides.py
│   └── make-patch.sh
└── patches/
    ├── excluded.txt
    ├── local-only.txt
    ├── upstream-migrations.tsv
    ├── local-overrides.json
    └── *.patch