fix(skills): keep package Markdown from blocking skill loads - #110461

What does this PR do?

A valid directory skill can become unloadable when another skill package contains an internal Markdown file with the same basename under an arbitrary directory such as prompts/. The recursive legacy flat-skill lookup records that internal file as an independent skill and reports a false ambiguity.

This change recognizes package ownership structurally: a Markdown candidate is not a legacy flat skill when an ancestor between it and the configured skills root contains SKILL.md. Genuine root-level and categorized legacy flat skills remain discoverable.

Symptom

Calling skill_view("research") refuses to load research/SKILL.md when another package contains prompts/research.md, returning Ambiguous skill name 'research'.

Impact

Users cannot load the intended skill unless they rename otherwise valid internal package content. The affected internal directory names are unbounded, so extending a fixed support-directory list does not solve the bug class.

Bug Cause

Trigger: tools/skills_tool.py:_collect_skill_candidates recursively scans for <name>.md legacy candidates.

Causal chain:

1. A directory skill contains internal Markdown whose basename matches another skill.
2. The legacy scan excludes only four named support directories and records the internal Markdown as a standalone skill.
3. Collision handling sees two candidates and refuses to load the real directory skill.

Why it is wrong: A nested Markdown file is package-owned whenever an ancestor inside the skills root contains SKILL.md; its immediate directory name does not determine ownership.

Working sibling / contrast: Root-level and categorized flat Markdown files without an ancestor directory skill are genuine legacy skills and remain candidates.

Ruled out: Collision refusal itself is not the defect. It remains necessary for genuinely independent same-name skills; the false candidate enters earlier during legacy discovery.

Fix

Exclude legacy Markdown candidates that have an ancestor directory skill, both for direct relative-path lookup and recursive basename lookup. Add regression tests for an internal prompts/research.md conflicting with a real research/SKILL.md and for preserving categorized legacy flat skills.

Related Issue

Closes #110456

Type of Change

• Bug fix (non-breaking change that fixes an issue)

Changes Made

• tools/skills_tool.py - detect and exclude package-owned Markdown from legacy skill candidates.
• tests/tools/test_skills_tool.py - cover arbitrary internal directories and preserve independent categorized legacy skills.

How to Test

1. Create a real research/SKILL.md skill.
2. Create another directory skill containing prompts/research.md.
3. Run scripts/run_tests.sh tests/tools/test_skills_tool.py -k 'package_owned_markdown or categorized_legacy_flat_markdown' -q and verify both regression tests pass.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run the focused regression tests and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Windows 11

Documentation & Housekeeping

• Relevant documentation updates are N/A
• cli-config.yaml.example updates are N/A
• CONTRIBUTING.md and AGENTS.md updates are N/A
• I've considered cross-platform impact; this uses pathlib filesystem operations
• Tool description/schema updates are N/A

Screenshots / Logs

Focused regression result: 2 passed.