# Plan: Global skills directory support

## Goal

Automatically scan `~/.config/swival/skills/` (respecting `XDG_CONFIG_HOME`) for skills, so users can install skills that are available across all projects without needing `skills_dir` in config.

## Current behavior

`discover_skills()` in `swival/skills.py:255` scans skills in this order:

1. `.swival/skills/` (project-local, highest precedence)
2. `.agents/skills/` (agent standard, lower precedence)
3. Each `--skills-dir` / `skills_dir` path (lowest precedence)

There is no automatic global directory. Users can work around this by adding `skills_dir = ["~/.config/swival/skills"]` to their global config, but it's not discoverable and requires manual setup.

## Proposed changes

### 1. `swival/skills.py` — `discover_skills()`

Insert a new scan step **after** `--skills-dir` processing (at the end, lowest precedence):

```python
# Scan global skills ($XDG_CONFIG_HOME/swival/skills/ or ~/.config/swival/skills/)
global_skills = config.global_config_dir() / "skills"
if global_skills.is_dir():
    resolved_global = global_skills.resolve()
    if resolved_global not in scanned:
        _scan_skills_dir(resolved_global, base_resolved, catalog, verbose)
        scanned.add(resolved_global)
```

This gives us the precedence order:

1. `.swival/skills/` — project-local (highest)
2. `.agents/skills/` — agent standard
3. `--skills-dir` paths — explicit extra dirs
4. `$XDG_CONFIG_HOME/swival/skills/` — global auto-discovered (lowest, new)

Global is lowest because it's implicit. Explicit `--skills-dir` entries are a deliberate user choice and should always be able to override a globally installed skill of the same name.

Global skills will typically have `is_local = False`, since `is_local` is derived from whether the resolved path is relative to `base_dir` (`skills.py:218`). In the unusual case where `XDG_CONFIG_HOME` or a symlink resolves inside the project, they would be treated as local — that's correct behavior, not a special case to handle. This means:
- They usually won't show a file path in the catalog prompt (correct — they're outside the project)
- They'll be auto-added to `allowed_dirs_ro` (already handled in `session.py:216`)
- They can usually only be accessed via `use_skill`, not by reading the SKILL.md directly

### 2. `swival/skills.py` — add import

Add `from swival import config` (or `from swival.config import global_config_dir`) at the top of the file. Currently `skills.py` doesn't import `config.py`.

### 3. `swival/config.py` — scaffold comment

Update the scaffold config template (around line 843) to mention the global skills directory:

```toml
# Global skills: place SKILL.md directories in $XDG_CONFIG_HOME/swival/skills/
# (defaults to ~/.config/swival/skills/)
# Additional skills directories (override global skills of the same name):
# skills_dir = ["../my-skills"]
```

### 4. Tests

Add tests in `tests/test_skills.py`:

- **`test_global_skills_discovered`** — Create a temp dir as fake global config dir, populate `skills/my-skill/SKILL.md`, monkeypatch `global_config_dir` to return it, call `discover_skills()`. Assert the skill appears. Don't hard-code `is_local` — it depends on whether the temp dir resolves inside `base_dir`, so assert based on the actual path relationship.
- **`test_global_skills_precedence_vs_project`** — Same skill name in project `.swival/skills/` and global dir. Assert the project-local version wins (its path points to the project dir).
- **`test_global_skills_precedence_vs_agents`** — Same skill name in `.agents/skills/` and global dir. Assert the `.agents/skills/` version wins.
- **`test_global_skills_precedence_vs_skills_dir`** — Same skill name in `--skills-dir` and global dir. Assert the `--skills-dir` version wins (explicit overrides implicit).
- **`test_global_skills_dir_missing`** — `global_config_dir()` points to a dir without `skills/`. No error, no skills from global.
- **`test_global_skills_dedup_with_skills_dir`** — Same path appears in both global and `--skills-dir`. Assert it's only scanned once (via `scanned` set).

### 5. Documentation

Update `docs.md/skills.md` (or equivalent) to document the global skills directory.

## What this does NOT change

- No new CLI flags or config keys
- No change to `--no-skills` behavior (it already skips all skill discovery)
- No change to `skills_dir` config — it continues to work as before
- No change to the `SkillInfo` dataclass or `use_skill` tool

## Risks

- Circular import: `skills.py` importing from `config.py`. Should be fine — `config.py` doesn't import `skills.py`.
- Users who already have `skills_dir = ["~/.config/swival/skills"]` in their global config will now scan the directory twice, but the `scanned` set deduplication handles this cleanly.
