SkillCustomization PREFERENCES.md not automatically applied in background agents — is this by design or misconfiguration?

[rolpro]

PAI Version: 5.0.0 | Algorithm v6.3.0
Platform: Linux (Ubuntu 24.04, kernel 6.8.0)
Claude Code version: claude-sonnet-4-6

Problem

When a background agent (spawned via Agent(..., run_in_background: true)) calls Skill("Knowledge", "ingest ..."), the ## Customization section in skills/Knowledge/SKILL.md instructs:

"Before executing, check for user customizations at: ~/.claude/PAI/USER/SKILLCUSTOMIZATIONS/Knowledge/"

This instruction is never followed in practice. Background agents treat their spawn prompt as the primary directive. The SKILL.md content — including the Customization section — is lower priority and gets skipped.

The result: PAI/USER/SKILLCUSTOMIZATIONS/Knowledge/PREFERENCES.md is silently ignored every time an INBOX background agent runs.

Setup

• PAI installed at ~/.claude/ on Linux (no launchd, Pulse started manually)
• settings.json has a PreToolUse hook with matcher=Skill → http://localhost:31337/hooks/skill-guard
• PAI/PULSE/modules/hooks.ts → handleSkillGuard() currently only does blocklist checking — no customization injection

Questions

1. Is the skill-guard hook supposed to inject SKILLCUSTOMIZATIONS/<Skill>/PREFERENCES.md as additionalContext and it is just not implemented yet in my version?
2. Or is the expectation that each spawn prompt manually includes an instruction to read PREFERENCES.md?
3. Is there a Linux-specific setup step I am missing (e.g. Pulse needs to run as a daemon so the hook fires reliably)?

What I tried

• Confirmed PREFERENCES.md exists and has content
• Confirmed the skill-guard HTTP hook fires (Pulse running, returns 200 pass-through)
• Confirmed handleSkillGuard() in hooks.ts has no customization loading logic
• Workaround added to CLAUDE.md Inbox-Pflicht rule: spawn prompt now explicitly includes instruction to read PREFERENCES.md

Proposed fix (implemented locally, not update-safe)

Extended handleSkillGuard() to async, reads SKILLCUSTOMIZATIONS/<skill>/PREFERENCES.md via case-insensitive dir scan, injects content as additionalContext in the hook response. Works when Pulse is running.

Would this be something to upstream into the public PAI repo?

[xg-gh-25]

You've independently discovered the core tension: static skill instructions (SKILL.md) vs dynamic runtime context (background spawn prompts) — and the hook is the right integration point.

To answer your questions directly:

Q1: Is skill-guard supposed to inject PREFERENCES.md?
Not in the base PAI distribution (as of 5.0.0). The hook contract is matcher → blocker/pass-through, not matcher → context injector. You're right that your extension (async read + additionalContext) is the natural fit — this should be upstreamed.

Q2: Should each spawn prompt manually include PREFERENCES.md?
No — that's brittle and defeats the purpose of hooks. Hooks exist so spawn prompts stay generic and skill-specific overrides get injected transparently. If you're adding PREFERENCES.md to every Inbox-Pflicht rule manually, that's a sign the hook layer is incomplete.

Q3: Linux-specific setup step?
No. The hook fires if Pulse is running (daemon vs manual doesn't matter — HTTP endpoint is HTTP endpoint). Your 200 pass-through confirms the plumbing works.

---

Architectural fix (what we run in production):

Our hook reads from SKILLCUSTOMIZATIONS/<Skill>/ on EVERY PreToolUse event where toolName == "Skill":

// hooks.ts :: handleSkillGuard
const skillName = extractSkillName(request.toolInput);  // "Knowledge" from Skill("Knowledge", ...)
const customPath = `${PAI_ROOT}/USER/SKILLCUSTOMIZATIONS/${skillName}/PREFERENCES.md`;

if (fs.existsSync(customPath)) {
  const prefs = await fs.promises.readFile(customPath, 'utf8');
  return {
    approved: true,
    additionalContext: prefs,
    reason: `Injected ${skillName} preferences`
  };
}

This way:

• Background agents get preferences automatically
• Spawn prompts stay clean (no per-skill include boilerplate)
• PREFERENCES.md becomes the runtime override surface for all skills

---

Your proposed fix is production-ready. Suggest you:

1. Upstream it to PAI as a feature (it's a 10-line addition to hooks.ts)
2. Document it in SKILLCUSTOMIZATIONS/README.md so users know the hook will inject their prefs
3. Add a test case: background agent runs Skill("Knowledge", "ingest ...") → preferences appear in context without manual spawn-prompt wiring

The gap you found is real: hooks are plumbing for policy (blocklist) but should also handle customization (preferences). Your fix closes that gap.

---

Running PAI + Pulse with customization injection in production for 4 months. SwarmAI. Discussion: T-CUL Cultivation > Config