Imported from magimetal/pi-skill-controller (extensions/skill-controller/AGENTS.md). Install upstream with npx skills add magimetal/pi-skill-controller --skill skill-controller. Copyright stays with the author.

ALWAYS READ THESE FILE(S)

• @../../AGENTS.md
• @AGENTS_CUSTOM.md

PROJECT KNOWLEDGE BASE: extensions/skill-controller

OVERVIEW

Core implementation for scoped Pi skill control: command registration, skill discovery, settings serialization, package-source resolution, and overlay UI.

STRUCTURE

extensions/skill-controller/
├── commands.ts                         # command handlers and transcript copy
├── create-skill-controller-extension.ts # extension bootstrap
├── discovery.ts                        # skill source aggregation
├── package-source.ts                   # npm/git/local package identity/root resolution
├── path-utils.ts                       # ~ expansion and settings-relative resolution
├── serialization.ts                    # enable/disable filter mutation
├── settings-store.ts                   # load/write scoped JSON settings
├── types.ts                            # shared contracts
└── ui.ts                               # TUI overlay component

WHERE TO LOOK

CONVENTIONS

• Internal imports must include .js suffix for ESM output compatibility.
• Keep filesystem/process calls behind SkillControllerDependencies when behavior needs tests.
• ScopeSettings.baseDir is settings file directory, not repo root.
• targetSettingsPath is carried into SkillRecord and UI copy; keep exact path intact.
• Package-managed skill toggles must preserve package identity and inherited non-skill filters.

ANTI-PATTERNS

• No as any, @ts-ignore, or swallowed filesystem/JSON errors.
• No broad path-glob matching for skill toggles; current serializer is exact path oriented.
• No write from discoverSkillsForScope; discovery is read-only.
• No direct process.env.HOME reads outside command/default loading boundary unless injectable.
• No overlay save side effect from Enter, arrows, typing, or Esc.

VERIFICATION

npm run typecheck
npm test

NOTES

• collectSkillDirs treats either a directory with SKILL.md or loose .md file as one skill source.
• Project .agents/skills roots walk from cwd up to git root; global .agents/skills uses home root.