[sbroenne]

Description

Fix the 1.0.1 skill-loading blocker and prepare the narrowly scoped corrective release 1.0.2. The package's local preflight rejected references/commands/ even though the SDK discovers the skill correctly. Four focused regression cases reproduced the exact failure before the fix.

The Agent Skills specification permits additional files and directories. Advice about one-level reference chains does not prohibit nested folders.

• Load Markdown references recursively, preserving sorted slash-separated paths relative to references/; flat names remain unchanged and equal basenames in different folders do not overwrite each other.
• Retain Markdown, UTF-8, nonempty-file, readability, and regular-file checks. Resolve links before traversal/reads; reject escaping targets, broken links, and directory cycles, including Windows junctions. Contained links remain supported.
• Cover individual/parent inputs, failures before SDK startup, single-attempt behavior, native evidence, plugin path collisions, public local preflight, and real SDK discovery/isolation without model execution.
• Document existing public load_skill() / Skill.from_path() as the local, unbilled preflight before SDK discovery. No new public API, forced reads, or retries.
• Align project version, version-only local lock metadata, release invariants, current docs tag examples, and dated 1.0.2 notes. Preserve historical 1.0.1 and unrelated Unreleased entries.

Updated authorization: the user has authorized completing this narrow corrective merge and patch release. The earlier merge/publication hold is superseded for this fix only. Use normal required checks and the documented guarded release workflow; no bypasses, force-pushes, or model spending. No ExcelMcp files or tests were touched.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Checklist

• I ran the deterministic checks required for this change
• I ran the relevant real-Copilot integration file when behavior changed
• I added contract or integration coverage that proves the outcome
• I updated user and contributor documentation where needed
• I did not include credentials or unsanitized private prompts

Testing

Exact commands and results:

uv run python -m pytest "tests\unit\test_skill.py" "tests\contracts\test_skill_availability.py" -q -o addopts= -k nested --tb=short
Before fix: 4 failed as expected with the reported directory rejection.

uv run python -m pytest "tests\unit\test_skill.py" "tests\unit\test_plugin_skill_references.py" "tests\unit\test_skill_workflow_support.py" "tests\contracts\test_skill_availability.py" -q -o addopts= --tb=short
Passed: 70 tests, including actual Windows symlink/junction safety checks.

uv lock
uv lock --directory "examples\skill-dogfood"
Passed: only local framework version changed from 1.0.1 to 1.0.2; no dependency upgrades.

uv run python -m pytest "tests\contracts" "tests\unit\test_skill.py" "tests\unit\test_plugin_skill_references.py" "tests\unit\test_skill_workflow_support.py" "tests\unit\test_release_invariants.py" "examples\skill-dogfood\tests\offline" -q -o addopts= --tb=short
Passed: 221 tests on 1.0.2 release preparation.

uv run python -m pytest "tests\integration\copilot\test_skill_discovery.py" -q -o addopts= --tb=short
Passed: 9 unbilled real-SDK cases. Eight forbid sends; one blocks HTTP/WebSocket forwarding before execution. Nested individual/parent inputs, exclusions, and ambient isolation verified.

uv run python -m pytest "examples\quickstart" --collect-only -q -o addopts=
Passed: 1 test collected, not executed. An initial nonexistent file selector was corrected to this directory selector; no model calls occurred.

uv run ruff check src tests examples
Passed.

uv run ruff format --check src tests examples
Passed: 143 files.

uv run pyright
Passed: 0 errors/warnings.

uv run python -X utf8 -m mkdocs build --strict
Passed.

uv build --out-dir "C:\Users\stefa\.copilot\session-state\777d77f2-d244-4af8-a079-b3786f6739d2\files\release-1.0.2"
Passed: source/wheel/sdist report 1.0.2.

uv run --no-project --isolated --with "C:\Users\stefa\.copilot\session-state\777d77f2-d244-4af8-a079-b3786f6739d2\files\release-1.0.2\pytest_skill_engineering-1.0.2-py3-none-any.whl" python -c "from pathlib import Path; from importlib.metadata import version; import pytest_skill_engineering as package; import pytest; assert version('pytest-skill-engineering') == package.__version__ == '1.0.2'; location = Path(package.__file__); assert 'site-packages' in location.parts and not location.is_relative_to(Path.cwd()); print('Installed local wheel 1.0.2:', location); raise SystemExit(pytest.main(['tests\\unit\\test_skill.py', 'tests\\unit\\test_plugin_skill_references.py', 'tests\\unit\\test_skill_workflow_support.py', 'tests\\contracts\\test_skill_availability.py', 'tests\\integration\\copilot\\test_skill_discovery.py', '-q', '-o', 'addopts=', '--tb=short']))"
Passed: 79 tests against confirmed installed local 1.0.2 wheel, including public preflight and real SDK checks. One expected pytest assertion-rewrite warning because the package is imported to verify its location before pytest starts.

uv run pre-commit run --files CHANGELOG.md "docs\getting-started\skills.md" "src\pytest_skill_engineering\core\plugin.py" "src\pytest_skill_engineering\core\skill.py" "tests\contracts\test_skill_availability.py" "tests\integration\copilot\test_skill_discovery.py" "tests\unit\test_plugin_skill_references.py" "tests\unit\test_skill.py"
Passed: lint, format, type check, docs build.

uv run pre-commit run --files pyproject.toml uv.lock "examples\skill-dogfood\uv.lock" CHANGELOG.md "tests\unit\test_release_invariants.py" ".github\workflows\docs.yml"
Passed: lint, format, type check; docs hook not applicable to these files (strict docs build independently passed).

Related Issues

Fixes #111

Follow-up to #109 and merged #110.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None