skills: fix the download path (Files API place, securable vs bundle name) and prompt before fetching

[xsh310]

Problem

Three problems in the ucode configure skills download path.

1. Bundle reads went to the wrong Files API place, so downloads never worked.
The client read bundle bytes from /Volumes/<cat>/<sch>/<leaf>, but a skill has no backing UC Volume. Listing succeeded (that goes through the 2.1 skills API), then every file fetch failed:

list_schema_skills -> ['ai-ops-oncall-daily', 'ai-ops-investigate', 'task-triage', 'work-recap', 'humanize']
list_skill_files   -> [] reason: HTTP 404 "Volume 'xsh.bb-0806.humanize' does not exist."

The unit tests mocked the HTTP layer and asserted the /Volumes/... URLs, so they encoded the bug instead of catching it, and no test pinned the listing URL at all.

2. A skill's two names were treated as one, so any skill whose names differ 404'd.
A skill has a securable name (the leaf of skills/<cat>.<sch>.<leaf>) and a bundle_name that FinalizeSkill parses from the bundle's SKILL.md frontmatter. Only the securable name resolves through the Files API, while bundle_name is what an agent looks for on disk. _skill_bundle_name preferred bundle_name and used it for both jobs, so fixing problem 1 exposed this:

! Skipping `xsh.bb-0806.task-triage`: HTTP 404 Not Found:
  "Path '/Skills/xsh/bb-0806/task-triage' did not resolve to a Unity Catalog skill."

Nothing keeps the two in sync. FinalizeSkillValidator.verifyFrontmatter checks the frontmatter name for emptiness, length, and control characters, but never compares it to the securable, so the divergence is permitted by design rather than being a data anomaly.

3. The overwrite dedup prompt ran after the bytes were already downloaded.
download_skills fetched every skill's full bundle up front, then prompted per skill at write time. Declining a skill threw away a download that had already completed, wasted work that scales with how much the user already has on disk, which is the common re-download case.

Change

Files API place (0768e1a): point the directory walk and the file fetch at the Skills place through a single SKILL_FILES_API_PREFIX constant.

Two names (fe1295b, 410f21f, 94fd4af): replace _skill_bundle_name with a frozen SkillRef(securable_name, bundle_name), so the type carries the distinction instead of leaving it to a bare string two callers read differently.

• Fetches take ref.securable_name, the only name the Files API resolves.
• Directories and dedup use ref.bundle_name, so the directory matches the name: in the SKILL.md written inside it.
• should_download_skill validates both names, since one reaches a URL and the other the filesystem.
• --skill matches the securable name only, since that is what identifies a skill in UC.
• A finalized skill missing either name is skipped with a warning naming the missing field, rather than substituting the other name. Guessing a directory that doesn't match the bundle's frontmatter would hide the skill from the agent meant to load it. An unfinalized skill is still skipped quietly, since having no bundle yet is a normal in-progress state.

Prompt before fetch (415e7c6, e056755): move the disk-only checks ahead of the fetch, so a declined or invalid skill is never downloaded. write_skill splits into should_download_skill (the decision, needs no bytes) and a pure writer. The per schema parallel fetch and the sequential for location in locations loop are unchanged, so cross location overwrite prompts still fire.

Tests

uv run pytest tests/test_skills_download.py gives 48 passed. Full suite excluding the live gateway e2e tests: 1274 passed, 6 skipped. uv run ruff check and the ty type check are clean.

Unit coverage added for each change:

• test_lists_under_the_skills_place pins the listing URL, previously unasserted, and the mocks that asserted /Volumes/... are updated.
• test_fetches_by_securable_and_writes_under_bundle_name asserts the fetch uses the securable name while the directory is the bundle name, and that no securable named directory is created.
• test_skill_filter_matches_securable_name_only asserts both directions: the securable name selects, the bundle name does not.
• test_either_unsafe_name_is_skipped covers an unsafe value in either position.
• test_skips_and_warns_when_a_name_is_missing is parametrized over all four missing name combinations, plus test_unfinalized_skill_is_skipped_without_a_warning for the quiet case.
• test_declined_skill_is_not_fetched asserts fetch_skill_bundle is never called for a declined skill and the existing copy is untouched.

End to end against a real workspace

Verified against xsh.bb-0806 on eng-ml-inference.staging, the workspace where both Skills flags are on. That schema contains a skill whose two names differ, which is what surfaced problem 2:

securable_name=ai-ops-oncall-daily    bundle_name=ai-ops-oncall-daily
securable_name=ai-ops-investigate     bundle_name=ai-ops-investigate
securable_name=task-prioritizer       bundle_name=task-triage        <-- differ
securable_name=work-recap             bundle_name=work-recap
securable_name=humanize               bundle_name=humanize

The two paths, confirmed directly against the Files API:

/Skills/xsh/bb-0806/task-triage       -> 404 "did not resolve to a Unity Catalog skill"
/Skills/xsh/bb-0806/task-prioritizer  -> 200, SKILL.md

Full schema download. download_skills(..., ["xsh.bb-0806"], path) reports Downloaded 5/5, up from 4/5 before the name fix, where task-triage was the one failure. The directories written are:

.claude/skills/  ai-ops-investigate  ai-ops-oncall-daily  humanize  task-triage  work-recap

The skill with differing names lands in task-triage/ (the bundle name), its bytes came from the task-prioritizer path (the securable name), and its SKILL.md frontmatter reads name: task-triage, so the directory and the frontmatter agree. No task-prioritizer/ directory is created, and both roots (.claude/skills and .agents/skills) receive it.

--skill on the mismatched skill. Requesting the securable name downloads it into the bundle named directory; requesting the bundle name is reported as not found:

--skill task-prioritizer  ->  Downloaded 1/1 skill(s)    (writes .claude/skills/task-triage/)
--skill task-triage       ->  Skipping requested skill(s) not found in `xsh.bb-0806`: task-triage.
                              No requested skills to download from `xsh.bb-0806`.

Bundle integrity. For a skill whose names match, the fetched bytes equal the sizes the Files API reports, and nested files are preserved:

files:  ['SKILL.md', 'references/ai-patterns.md']
bundle: {'SKILL.md': 9176, 'references/ai-patterns.md': 21848}

Note that the server side /Skills byte path is still gated by databricks.unitycatalog.aigov.enableSkillsFilesApi, which is default off and enabled only for that test workspace. This PR does not change that gating, it just stops ucode from asking the wrong place with the wrong name.

This pull request and its description were written by Isaac.