skills: add download mode to ucode configure skills (client, writer, CLI wiring)

[xsh310]

What

Completes download mode for ucode configure skills, end to end. Downloads every Unity Catalog skill in a schema to local disk and registers a schema-less skills MCP connection. This PR covers the whole path: the read-only client, the on-disk writer, the CLI wiring, and docs.

Stacked on #236. This branch is rebased on top of skills-mcp-mode (PR #236, MCP mode). Because that branch lives in a fork, GitHub cannot set it as this PR's base, so the base stays main and the diff shown here includes #236's commits until it merges. Review only the download commits (b2ffa9a onward); the first six commits are #236. Once #236 merges into main, this diff self-cleans.

Download client + writer + orchestration (src/ucode/skills_download.py, new module):

• list_schema_skills(...) returns finalized skill leaf names in a schema via the UC skills API (GET /api/2.1/unity-catalog/skills?parent=schemas/<cat>.<sch>, paginated). Uses bundle_name as the leaf and the presence of finalize_time as the readiness signal.
• list_skill_files(...) returns a bundle's files as paths relative to the skill directory, by recursively walking its UC Volume directory (GET /api/2.0/fs/directories/Volumes/<cat>/<sch>/<leaf>, paginated).
• fetch_skill_file(...) returns one file's raw bytes; fetch_skill_bundle(...) composes list + fetch into {relpath: bytes}, all or nothing (any failure returns a reason and no bundle, so a partial skill is never written).
• skill_dir_roots(path) returns the .claude/skills + .agents/skills roots. path is optional: given, it must be an existing absolute directory; omitted, roots default to the home directory (user scope).
• write_skill(...) writes a skill's {relpath: bytes} bundle into every root, one flat <root>/<leaf>/ dir per skill. It prompts before overwriting any pre-existing skill dir (ucode does not track which schema wrote a dir, so it always asks). Rejects invalid leaf names and ../absolute paths in the bundle.
• download_skills(...) fetches a schema's bundles concurrently (with a k/n progress bar), then writes them sequentially so overwrite prompts do not interleave. A per-skill failure warns and skips without aborting the batch, and it prints a Downloaded k/n skill(s) summary.
• configure_skills_download_command(locations, *, path) is the command entry point: resolves clients + token, calls download_skills, then registers or keeps the schema-less MCP connection.

Shared transport (src/ucode/databricks.py): _http_get_bytes, a raw-bytes GET helper next to _http_get_json, since bundles can contain binary files.

MCP glue (src/ucode/mcp.py): setup_mcp_clients (promoted from private) and register_schemaless_skills_connection, which preserves any prior --mcp skill_locations and otherwise registers the bare schema-less route. mcp.py holds no download logic; the dependency flows one way (cli to skills_download to mcp to databricks).

CLI (src/ucode/cli.py): --mcp is optional and --path is download-only. Download is the default mode; --mcp opts into the connection-only mode; --path with --mcp is rejected. skill_locations is never touched by download, so a prior --mcp scope survives a download run.

Docs (README.md, AGENTS.md): a Skills subsection and Other Commands rows covering both modes, the optional --path with its home-dir default, the flat layout, the collision prompt, and the schema-less connection; module-boundary note for skills_download.py.

Test plan

Unit tests (no network, mocked HTTP / patched prompt_yes_no):

• tests/test_skills_download.py: the client (list_schema_skills finalized-only filter + pagination, list_skill_files recursive walk + pagination, fetch_skill_file, fetch_skill_bundle all-or-nothing); the writer (skill_dir_roots project + home-default + reject relative/missing, write_skill into both roots, nested files, collision prompt keep/overwrite, invalid-leaf skip, ../absolute path rejection); the orchestrator (download_skills fetch-and-write, list-failure skip, per-skill bundle-failure skip, k/n summary counts only written skills); and the command wiring (configure_skills_download_command downloads then registers, threads a None path).
• tests/test_mcp.py: _skill_mcp_locations, register_schemaless_skills_connection (registers the bare route, preserves a prior --mcp set), plus revert/purge lifecycle coverage for the skills entry.
• tests/test_cli.py: two-mode dispatch (default downloads with and without --path, --mcp sets the connection, --path + --mcp rejected, malformed --location).

Full suite: 952 passing, 39 skipped, 1 pre-existing unrelated test_e2e_user_agent failure (spawns a live claude subprocess; also fails on the base commit). ruff check, ruff format --check, and ty check src/ all clean (these are the CI gates in test_lint.py).

Live end-to-end against a staging workspace (eng-ml-inference.staging, user OAuth token, location xsh.uc_skill_test). Drove the real configure_skills_download_command with only the agent-config writes and state persistence patched out, so the network fetch, the write, and the connection registration all ran for real. Three scenarios on the latest commit:

1. Project scope (--path <dir>, fresh): pii-handling downloaded with its full nested bundle (SKILL.md + 5 references/*.md + 2 templates/*) into both .claude/skills/ and .agents/skills/ (16 files total); SKILL.md had real frontmatter, not a stub. The progress bar advanced 0/3 to 3/3 during the concurrent fetch and cleared. Summary: Downloaded 1/3 skill(s) from xsh.uc_skill_test. Schema-less connection registered (URL .../ai-gateway/skills/, skill_locations: [], clients [claude, codex]).
2. Project scope, re-run: prompted A skill named 'pii-handling' already exists. Overwrite it with 'xsh.uc_skill_test.pii-handling'? before writing, confirming the collision path.
3. Home scope (--path omitted, Path.home() pointed at a temp dir): the same 16 files landed under the home-dir roots, confirming the optional---path default.

In all three, the two other listed leaves (xsh-format, dataset-boundary) have no Volume in staging and returned a real HTTP 404 Volume ... does not exist; each was skipped with a warning and the batch continued (exit 0). Scratch dirs were removed afterward and real ucode state was never written.

The earlier client-only e2e also resolved a real design question: ucode's client-side OAuth token reads all three endpoints directly, so no GenerateTemporaryStorageCredentials vending is needed. It corrected two assumptions unit tests alone would miss: the deployed endpoint is /api/2.1/unity-catalog/skills (not the managed-catalog-aigov path), and readiness is finalize_time (there is no status field).

Notes

• Draft until reviewed.