skill-scope-manager

# Skill Scope Manager

Use this skill to manage the scoped skill registry for the current machine.

## Source of truth

Always read `registry/skill-registry.yaml` first. Treat it as the authority for:

- which skills are managed
- which scopes exist
- which absolute paths each skill instance uses
- whether a skill is globally enabled or disabled
- whether bootstrap initialization is complete

Use `registry/skill-registry.md` as the human-readable table view only.

If `registry/skill-registry.yaml` does not exist, or `bootstrap_complete` is false, also read `references/bootstrap_init.md` before doing any initialization work. Do not load that file during normal daily management.

## Defaults

- Preview first, then apply
- Same skill name may exist in multiple scopes
- A skill with multiple scoped copies is considered active in each of those scopes
- For skill content edits, first resolve the absolute path from the registry, then edit that path
- This skill is not a background watcher; new skill folders become managed only after `discover`/`audit`/`register`
- **Important**: Whenever the skill registry or related skill components are modified, you MUST commit the changes to the git repository located in this skill's directory (`/Users/tmyz/.config/opencode/skills/skill-scope-manager`).

## Commands

For daily management, run the helper script from this skill directory:

```bash
python scripts/skill_scope_registry.py list
python scripts/skill_scope_registry.py where <skill-name>
python scripts/skill_scope_registry.py here --cwd "$PWD"
python scripts/skill_scope_registry.py audit
python scripts/skill_scope_registry.py discover --unregistered-only
python scripts/skill_scope_registry.py borrow-preview --query <text> --cwd "$PWD"
python scripts/skill_scope_registry.py borrow-resolve --skill-name <name> --cwd "$PWD"
python scripts/skill_scope_registry.py register --skill-dir <path> --scope-root <scope>
python scripts/skill_scope_registry.py remove --skill-name <name> --scope-root <scope>
python scripts/skill_scope_registry.py disable --skill-name <name>
python scripts/skill_scope_registry.py enable --skill-name <name>
python scripts/skill_scope_registry.py move --skill-name <name> --from-scope-root <src> --to-scope-root <dst>
python scripts/skill_scope_registry.py sync-agents
```

Add `--apply` to any mutating command after showing the preview to the user.

For first-run initialization only, use the dedicated initialization script:

```bash
python scripts/skill_scope_init.py init-status
python scripts/skill_scope_init.py init-discover --skill-dir <path> [--skill-dir <path> ...]
python scripts/skill_scope_init.py init-preview --decision-file <file> [--plan-out <file>]
python scripts/skill_scope_init.py init-apply --plan-file <file>
```

## Workflow

### Initialization

Initialization is a separate mode. If the registry is missing or `bootstrap_complete` is false:

1. Read `references/bootstrap_init.md`
2. Determine the central fixed path where `skill-scope-manager` should be permanently stored (e.g. `~/Vscode/SKILL/skill-scope-manager`)
3. Determine all target agent global directories (e.g. `~/.codex/skills`, `~/.config/opencode/skills`)
4. Create symlinks from each agent directory pointing back to the central path
5. Use `scripts/skill_scope_init.py` to bootstrap the registry, creating independent global scopes (e.g., `codex_global`, `opencode_global`) to isolate each agent's global skills while sharing the same central registry file.
6. Do not improvise the bootstrap flow from the daily management commands

During initialization, make sure the global `AGENTS.md` also gets a stable guidance block that tells the agent:

- global skill disable requires both `skill-scope-manager` and Codex system settings
- global skill re-enable requires both `skill-scope-manager` and Codex system settings
- newly installed and newly created skills are not scope-managed until `register` is applied

### Add

Use `discover --unregistered-only` to find new skills. Then:

1. Ask the user which scope root should own the new skill
2. Run `register` without `--apply`
3. Show the preview
4. Re-run with `--apply`

If a user has just created a skill, explicitly remind them that the new folder is not scope-managed until registration is applied.

### Remove

Use `where <skill-name>` first.

- If a skill has one instance, remove it directly
- If a skill has multiple instances, ask which scoped copy to remove

Always preview first.

### Disable or enable

Use `disable` and `enable` for a lightweight, recoverable switch.

- `disable` keeps the skill directory and registry entry intact
- `enable` restores the skill from the same registry entry
- Disabled state belongs in the registry, not in `AGENTS.md`
- `AGENTS.md` should only list currently active skills

When the user wants a skill fully hidden, remind them that there are two separate layers:

1. Disable it in `skill-scope-manager` so local scope resolution and `AGENTS.md` stop exposing it
2. Disable it in Codex system settings as well if they also want the client-level global skill list to stop surfacing it

For global skills, the inverse is also true when re-enabling:

1. Enable it in `skill-scope-manager` so local scope resolution and `AGENTS.md` can expose it again
2. Enable it in Codex system settings as well if they also want the client-level global skill list to surface it again

Use `remove` only when the user wants to delete the scoped copy itself.

### Modify

Use `where <skill-name>` to resolve the absolute path.

- If there is one instance, edit that path
- If there are multiple instances, ask whether to edit one instance or all instances

If the change is a scope change rather than a content change, use `move`.

### Query

- `list`: all managed skills and their scopes
- `where <skill-name>`: all absolute paths for that skill
- `here --cwd <path>`: which skills are active in a path
- `audit`: registry, disk, and AGENTS.md drift

### Temporary cross-scope invocation

Use this workflow when the user explicitly wants to call a skill that is outside the current scope.

1. Resolve candidates with `borrow-preview`
2. If needed, narrow to a single target with `borrow-resolve`
3. Show the user:
   - the target skill name
   - the target scope
   - the absolute `SKILL.md` path
   - that this is a one-time, out-of-scope invocation
4. Only after the user confirms, read the target `SKILL.md`
5. Use that skill for the current task only

Rules:

- Do not modify `AGENTS.md`
- Do not modify registry scope assignments
- Do not add the target skill to the current scope
- Do not cache approvals across the session
- Every out-of-scope invocation requires a fresh explanation and a fresh confirmation

If the requested skill is already available in the current scope, say so and do not treat it as a borrow.

#### User confirmation template

When an out-of-scope skill has been resolved, use a clear confirmation message before reading that skill.

Use this template:

```text
The skill you requested is outside the current scope.

Target skill: <skill-name>
Target scope: <scope-root>
Target SKILL.md: <absolute-skill-md-path>

Before I borrow this out-of-scope skill, please use the client's slash permission command to give the agent enough access for this task.

Use at least Default Access. If this borrowed skill may need broader filesystem reads or execution outside the current scope, switch to Full Access first.

After that, please explicitly confirm that I may read and execute this out-of-scope skill for this one invocation.

This borrow is one-time only:
- it will not change AGENTS.md
- it will not change the registry
- it will not add the skill to the current scope
- it will not persist after this task

If you approve, I will load this skill and use it once for the current task.
```

Rules for this confirmation:

- Always show the absolute `SKILL.md` path
- Always say that the skill is outside the current scope
- Always ask for explicit approval before reading the target `SKILL.md`
- Always tell the user to adjust the agent's access level through the client's slash permission command before approving the borrow
- Always mention `Default Access` as the minimum recommended level
- Always mention `Full Access` when broader filesystem reads or execution may be needed
- Even if the current environment already appears to have enough filesystem access, still require explicit user approval as a scope-boundary confirmation
- If the user does not approve, stop the borrow flow and continue without loading the out-of-scope skill

## AGENTS.md management

Use `sync-agents` to maintain a managed block inside each scope's `AGENTS.md`.

Managed block markers:

```md
<!-- skill-scope-manager:begin -->
...
<!-- skill-scope-manager:end -->
```

Do not overwrite content outside this block.

## References

- Registry schema and behavior details: `references/registry_schema.md`
- Initialization-only guide: `references/bootstrap_init.md`