diff --git a/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs b/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs
index f9d5dcc5328..d58328ab3ac 100644
--- a/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs
@@ -17,6 +17,7 @@ namespace Microsoft.Agents.AI;
/// Supports ZIP payloads. Extraction is guarded against path-traversal ("zip-slip") attacks and
/// bounded by a maximum file count and total uncompressed size to mitigate decompression-bomb attacks.
/// Later entries resolving to an existing file are skipped, preserving the first file's content.
+/// Archives containing file names that differ only by case are rejected.
///
internal static partial class AgentMcpSkillArchiveExtractor
{
@@ -83,7 +84,7 @@ internal static ArchiveFormat DetectFormat(byte[] bytes, string? mediaType, stri
/// The maximum total uncompressed size, in bytes, of all extracted files.
/// An optional logger reporting each skipped colliding archive member.
/// The format is not .
- /// The archive exceeds one of the supplied limits.
+ /// The archive exceeds one of the supplied limits or contains file names that differ only by case.
internal static void Extract(
byte[] bytes,
ArchiveFormat format,
@@ -113,7 +114,7 @@ private static void ExtractZip(Stream source, string fullTarget, int maxFileCoun
long remainingBytes = maxUncompressedSizeBytes;
int fileCount = 0;
- var destinations = new HashSet(OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal);
+ var destinations = new Dictionary(StringComparer.OrdinalIgnoreCase);
string skillName = SanitizePathForLog(Path.GetFileName(fullTarget));
foreach (ZipArchiveEntry entry in archive.Entries)
@@ -136,12 +137,19 @@ private static void ExtractZip(Stream source, string fullTarget, int maxFileCoun
}
// Normalization can map distinct archive names to one path; keep the first file.
- if (!destinations.Add(destination))
+ if (destinations.TryGetValue(destination, out string? previous))
{
+ if (!string.Equals(previous, destination, StringComparison.Ordinal))
+ {
+ throw new InvalidDataException("Skill archive contains file names that differ only by case.");
+ }
+
LogArchiveMemberCollision(logger, skillName, SanitizePathForLog(entry.FullName));
continue;
}
+ destinations.Add(destination, destination);
+
Directory.CreateDirectory(Path.GetDirectoryName(destination)!);
// CreateNew also prevents overwrites through filesystem aliases, such as trailing dots on Windows.
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs
index 5484348c59e..34a91b34b90 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs
@@ -27,6 +27,9 @@ namespace Microsoft.Agents.AI;
/// value is retained for duplicate keys, and subsequent entries produce warnings without rejecting the skill.
/// Resource and script files are discovered by scanning the skill
/// directory for files with matching extensions. Invalid resources are skipped with logged warnings.
+/// Skills whose resource names or script names differ only by case are skipped.
+/// Names are compared using ; Unicode equivalence
+/// follows the target runtime.
/// Resource and script paths are checked against path traversal and symlink escape attacks.
/// Discovered files are revalidated against their trusted skill directory immediately before use.
///
@@ -223,6 +226,12 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull
var resources = this.DiscoverResourceFiles(scope, frontmatter.Name);
var scripts = this.DiscoverScriptFiles(scope, frontmatter.Name);
+ if (this.HasCaseVariantNames(frontmatter.Name, "resource", resources.Select(r => r.Name)) ||
+ this.HasCaseVariantNames(frontmatter.Name, "script", scripts.Select(s => s.Name)))
+ {
+ return null;
+ }
+
return new AgentFileSkill(
frontmatter: frontmatter,
content: content,
@@ -231,6 +240,31 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull
scripts: scripts);
}
+ ///
+ /// Checks for collisions among the supplied names using
+ /// and logs the first collision.
+ ///
+ /// The owning skill's name, used only in the log message, not in comparisons.
+ /// The entry category ("resource" or "script"), used only in the log message.
+ /// The resource or script names to compare with each other.
+ /// if a collision is found; otherwise, .
+ private bool HasCaseVariantNames(string skillName, string kind, IEnumerable entryNames)
+ {
+ var seen = new Dictionary(StringComparer.OrdinalIgnoreCase);
+ foreach (string name in entryNames)
+ {
+ if (seen.TryGetValue(name, out string? previous))
+ {
+ LogCaseVariantNames(this._logger, skillName, kind, SanitizePathForLog(previous), SanitizePathForLog(name));
+ return true;
+ }
+
+ seen.Add(name, name);
+ }
+
+ return false;
+ }
+
private bool TryParseFrontmatter(string content, string skillFilePath, [NotNullWhen(true)] out AgentSkillFrontmatter? frontmatter)
{
frontmatter = null;
@@ -785,6 +819,9 @@ private static void ValidateExtensions(IEnumerable? extensions)
[LoggerMessage(LogLevel.Error, "SKILL.md at '{SkillFilePath}': skill name '{SkillName}' does not match parent directory name '{DirectoryName}'")]
private static partial void LogNameDirectoryMismatch(ILogger logger, string skillFilePath, string skillName, string directoryName);
+ [LoggerMessage(LogLevel.Error, "Skipping skill '{SkillName}': {Kind} names '{FirstName}' and '{SecondName}' differ only by case")]
+ private static partial void LogCaseVariantNames(ILogger logger, string skillName, string kind, string firstName, string secondName);
+
[LoggerMessage(LogLevel.Warning, "Skipping resource in skill '{SkillName}': '{ResourcePath}' references a path outside the skill directory")]
private static partial void LogResourcePathTraversal(ILogger logger, string skillName, string resourcePath);
diff --git a/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs b/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs
index 6a4ed11b222..fe3db8cb764 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs
@@ -259,7 +259,6 @@ public static TheoryData ArchiveCollisionCases
};
if (OperatingSystem.IsWindows())
{
- aliases.Add("refs/POLICY.md");
aliases.Add("refs/policy.md.");
}
@@ -312,8 +311,7 @@ public async Task GetSkillsAsync_CollidingArchiveResources_KeepsFirstFileAndLogs
for (int i = 0; i < 2; i++)
{
var skill = Assert.Single(await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create()));
- string resourceName = aliasFirst && alias == "refs/POLICY.md" ? alias : "refs/policy.md";
- var resource = await skill.GetResourceAsync(resourceName);
+ var resource = await skill.GetResourceAsync("refs/policy.md");
Assert.NotNull(resource);
Assert.Equal("First resource.", await resource.ReadAsync());
var other = await skill.GetResourceAsync("refs/other.md");
@@ -334,6 +332,46 @@ public async Task GetSkillsAsync_CollidingArchiveResources_KeepsFirstFileAndLogs
Times.Exactly(2));
}
+ [Theory]
+ [InlineData("refs/policy.md", "refs/POLICY.md", false)]
+ [InlineData("refs/policy.md", "refs/POLICY.md", true)]
+ [InlineData("refs/policy.md", "REFS/policy.md", false)]
+ [InlineData("refs/policy.md", "REFS/policy.md", true)]
+ [InlineData("scripts/run.py", "scripts/RUN.py", false)]
+ [InlineData("scripts/run.py", "scripts/RUN.py", true)]
+ [InlineData("SKILL.md", "skill.md", false)]
+ [InlineData("SKILL.md", "skill.md", true)]
+ public async Task GetSkillsAsync_CaseVariantArchiveNames_SkipsSkillAsync(string name, string variant, bool variantFirst)
+ {
+ // Arrange
+ var files = new List<(string Path, string Content)>
+ {
+ (variantFirst ? variant : name, ArchivedSkillMd),
+ (variantFirst ? name : variant, ArchivedSkillMd),
+ };
+ if (!string.Equals(name, "SKILL.md", StringComparison.Ordinal))
+ {
+ files.Add(("SKILL.md", ArchivedSkillMd));
+ }
+
+ byte[] archive = BuildZip(files.ToArray());
+ await using var server = CreateArchiveServer(
+ ArchiveIndex("archived-skill", "skill://archives/archived-skill.zip"),
+ new Dictionary { ["archived-skill"] = archive });
+ await using var client = await server.CreateClientAsync();
+ var source = new AgentMcpSkillsSource(client, new() { ArchiveSkillsDirectory = this._extractionRoot });
+
+ for (int i = 0; i < 2; i++)
+ {
+ // Act
+ var skills = await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create());
+
+ // Assert
+ Assert.Empty(skills);
+ Assert.False(Directory.Exists(Path.Combine(this._extractionRoot, "archived-skill")));
+ }
+ }
+
[Theory]
[InlineData("SKILL.md", false)]
[InlineData("SKILL.md", true)]
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
index 1599023e1b7..3603498d9a2 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
@@ -2151,6 +2151,41 @@ public async Task GetSkillsAsync_DeepResource_DiscoveredWithHigherDepthAsync()
Assert.Equal("f1/f2/f3/data.json", skill.GetTestResources()![0].Name);
}
+ [Theory]
+ [InlineData("test.md", "TEST.md")]
+ [InlineData("refs/test.md", "REFS/test.md")]
+ [InlineData("scripts/run.py", "scripts/RUN.py")]
+ [InlineData("\u00e9.md", "\u00c9.md")]
+ [InlineData("scripts/\u00e9.py", "scripts/\u00c9.py")]
+#if NET10_0_OR_GREATER
+ [InlineData("\u03a3.md", "\u03c2.md")]
+ [InlineData("scripts/\u03a3.py", "scripts/\u03c2.py")]
+#endif
+ public async Task GetSkillsAsync_NamesDifferOnlyByCase_SkipsSkillAsync(string firstName, string secondName)
+ {
+ // Arrange
+ string skillDir = this.CreateSkillDirectory("case-skill", "A skill", "Body.");
+ string firstPath = Path.Combine(skillDir, firstName);
+ string secondPath = Path.Combine(skillDir, secondName);
+ Directory.CreateDirectory(Path.GetDirectoryName(firstPath)!);
+ Directory.CreateDirectory(Path.GetDirectoryName(secondPath)!);
+ File.WriteAllText(firstPath, "first");
+ File.WriteAllText(secondPath, "second");
+ if (Directory.EnumerateFiles(skillDir, "*", SearchOption.AllDirectories).Count() != 3)
+ {
+ Assert.Skip("The filesystem is not case-sensitive.");
+ }
+
+ this.CreateSkillDirectory("other-skill", "A skill", "Body.");
+ var source = new AgentFileSkillsSource(this._testRoot, s_noOpExecutor);
+
+ // Act
+ var skills = await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create());
+
+ // Assert
+ Assert.Equal("other-skill", Assert.Single(skills).Frontmatter.Name);
+ }
+
private string CreateSkillDirectory(string name, string description, string body)
{
string skillDir = Path.Combine(this._testRoot, name);
diff --git a/python/packages/core/agent_framework/_skills.py b/python/packages/core/agent_framework/_skills.py
index 464d79ac7e2..4fd42e7ddf5 100644
--- a/python/packages/core/agent_framework/_skills.py
+++ b/python/packages/core/agent_framework/_skills.py
@@ -1851,6 +1851,11 @@ async def get_script(self, name: str) -> SkillScript | None:
class FileSkill(Skill):
"""A :class:`Skill` discovered from a filesystem directory backed by a SKILL.md file.
+ Resource and script lookup is case-insensitive, so two resources or two
+ scripts whose names differ only by case (e.g. ``readme.md`` and
+ ``README.md``) are ambiguous and rejected with :class:`ValueError`.
+ Comparison uses :meth:`str.lower`, not :meth:`str.casefold`.
+
Attributes:
path: Absolute path to the directory containing this skill.
"""
@@ -1874,6 +1879,9 @@ def __init__(
path: Absolute path to the skill directory on disk.
resources: Resources discovered for this skill.
scripts: Scripts discovered for this skill.
+
+ Raises:
+ ValueError: If resource or script names differ only by case.
"""
self._frontmatter = frontmatter
@@ -1881,6 +1889,8 @@ def __init__(
self.path = path
self._resources: list[SkillResource] = list(resources) if resources is not None else []
self._scripts: list[SkillScript] = list(scripts) if scripts is not None else []
+ self._reject_case_variant_names(frontmatter.name, "resource", self._resources)
+ self._reject_case_variant_names(frontmatter.name, "script", self._scripts)
self._cached_content: str | None = None
@property
@@ -1938,6 +1948,21 @@ async def get_script(self, name: str) -> SkillScript | None:
name_lower = name.lower()
return next((s for s in self._scripts if s.name.lower() == name_lower), None)
+ @staticmethod
+ def _reject_case_variant_names(skill_name: str, kind: str, entries: Sequence[SkillResource | SkillScript]) -> None:
+ """Reject names with equal ``str.lower()`` keys, matching resource and script lookup.
+
+ Raises:
+ ValueError: If two names differ only by case.
+ """
+ names: dict[str, str] = {}
+ for entry in entries:
+ previous = names.setdefault(entry.name.lower(), entry.name)
+ if previous != entry.name:
+ raise ValueError(
+ f"Skill '{skill_name}' has {kind} names that differ only by case: '{previous}' and '{entry.name}'."
+ )
+
# endregion
@@ -3143,6 +3168,9 @@ class FileSkillsSource(SkillsSource):
Use *script_filter* and *resource_filter* predicates to control which
discovered files are included.
+ Resource and script names that differ only by case skip the whole skill
+ with a warning.
+
Security: file-based metadata is XML-escaped before prompt injection,
and resource reads are guarded against path traversal and symlink escape.
Only use skills from trusted sources.
@@ -3295,13 +3323,17 @@ async def get_skills(self, context: SkillsSourceContext) -> list[Skill]:
)
)
- file_skill = FileSkill(
- frontmatter=frontmatter,
- content=content,
- path=skill_path,
- resources=resources,
- scripts=scripts,
- )
+ try:
+ file_skill = FileSkill(
+ frontmatter=frontmatter,
+ content=content,
+ path=skill_path,
+ resources=resources,
+ scripts=scripts,
+ )
+ except ValueError as exc:
+ logger.warning("Skipping skill '%s' at '%s': %s", frontmatter.name, skill_path, exc)
+ continue
skills[file_skill.frontmatter.name] = file_skill
logger.info("Loaded skill: %s", file_skill.frontmatter.name)
@@ -5029,8 +5061,7 @@ def _extract_archive_to_memory(
``..`` parent-traversal ("zip-slip") aborts extraction of the whole archive by
raising. Extraction is bounded by a maximum file count and total uncompressed size
to mitigate decompression-bomb attacks. No filesystem is touched.
- Later members whose normalized paths match case-insensitively are skipped
- with a warning; the first member's spelling and content are retained.
+ Duplicate normalized member paths reject the archive.
Args:
data: The raw archive bytes.
@@ -5043,7 +5074,7 @@ def _extract_archive_to_memory(
Raises:
ValueError: If the format is unknown, a limit is exceeded, or a member attempts
- a path-traversal ("zip-slip") escape.
+ a path-traversal ("zip-slip") escape, or two members normalize to the same path.
OSError: If the payload cannot be read.
zipfile.BadZipFile: If a ZIP payload is malformed.
"""
@@ -5061,7 +5092,6 @@ def _extract_zip_to_memory(
"""Read regular files from a ZIP archive into memory. See :func:`_extract_archive_to_memory`."""
remaining_bytes = max_uncompressed_size_bytes
files: dict[str, bytes] = {}
- seen_names: set[str] = set()
file_count = 0
for info in archive.infolist():
@@ -5075,22 +5105,12 @@ def _extract_zip_to_memory(
name = _normalize_archive_member_name(info.filename)
if name is None:
continue
-
- # Match FileSkill's case-insensitive lookup; retain the first member's spelling.
- lookup_name = name.lower()
- if lookup_name in seen_names:
- logger.warning(
- "Skipping duplicate archive member %r: normalized path %r matches an earlier member; "
- "keeping the first file",
- info.filename,
- name,
- )
- continue
+ if name in files:
+ raise ValueError(f"Duplicate archive member {info.filename!r}: normalized path {name!r}.")
with archive.open(info) as source:
content, remaining_bytes = _read_member_with_limit(source, remaining_bytes)
files[name] = content
- seen_names.add(lookup_name)
return files
@@ -5110,8 +5130,8 @@ class _ArchiveEntryLoader:
Extraction is hardened against path-traversal ("zip-slip") member names,
oversized downloads, excessive file counts, and decompression bombs.
- Member paths are compared case-insensitively; collisions are skipped with a
- warning, keeping the first file's spelling and content.
+ Duplicate normalized member paths reject the archive, and resource names that
+ differ only by case reject the skill.
Supplied SHA-256 digests are verified before extraction; archives without
a digest remain supported.
"""
@@ -5273,7 +5293,11 @@ def _build_skill(self, entry: _McpSkillIndexEntry, data: bytes, mime_type: str |
def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) -> FileSkill | None:
"""Assemble an in-memory :class:`FileSkill` from the archive's extracted files."""
- skill_md_key = self._find_skill_md(files)
+ try:
+ skill_md_key = self._find_skill_md(files)
+ except ValueError as exc:
+ logger.warning("Skipping skill '%s': %s", entry.name, exc)
+ return None
if skill_md_key is None:
logger.warning("Skipping skill '%s': archive contains no SKILL.md", entry.name)
return None
@@ -5305,20 +5329,26 @@ def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes])
# ``path`` records the archive's origin URL; it is informational only, as the
# skill and its resources are served entirely from memory (no filesystem access).
- return FileSkill(
- frontmatter=frontmatter,
- content=content,
- path=cast(str, entry.url),
- resources=resources,
- scripts=[],
- )
+ try:
+ return FileSkill(
+ frontmatter=frontmatter,
+ content=content,
+ path=cast(str, entry.url),
+ resources=resources,
+ scripts=[],
+ )
+ except ValueError as exc:
+ logger.warning("Skipping skill '%s': %s", entry.name, exc)
+ return None
@staticmethod
def _find_skill_md(files: dict[str, bytes]) -> str | None:
- """Return the key of the shallowest ``SKILL.md`` (case-insensitive), or ``None``."""
+ """Return the shallowest ``SKILL.md`` key, rejecting manifest paths that differ only by case."""
candidates = [key for key in files if key.rsplit("/", 1)[-1].upper() == SKILL_FILE_NAME.upper()]
if not candidates:
return None
+ if len({key.lower() for key in candidates}) != len(candidates):
+ raise ValueError("Archive contains SKILL.md paths that differ only by case.")
# Prefer the shallowest SKILL.md; break ties deterministically by name.
return min(candidates, key=lambda key: (key.count("/"), key))
@@ -5386,9 +5416,8 @@ class MCPSkillsSource(SkillsSource):
archive are surfaced as read-only resources only; MCP-delivered scripts
are never discovered as runnable.
- Archive member paths are compared case-insensitively, matching resource lookup.
- The first file's spelling and content are retained; later colliding members
- are skipped with a warning.
+ Archive resource names that differ only by case, or members that normalize
+ to the same path, skip the whole archive skill with a warning.
Entries whose type has no registered handler (e.g. ``mcp-resource-template``)
are skipped.
diff --git a/python/packages/core/tests/core/test_mcp_skills.py b/python/packages/core/tests/core/test_mcp_skills.py
index ac7b122d4ed..4b8bf6994d4 100644
--- a/python/packages/core/tests/core/test_mcp_skills.py
+++ b/python/packages/core/tests/core/test_mcp_skills.py
@@ -1536,7 +1536,7 @@ async def test_zip_slip_archive_skips_whole_skill(self) -> None:
class TestMCPSkillsSourceArchiveCollisions:
- """Colliding archive members warn and preserve the first file through discovery."""
+ """Colliding archive members reject only the affected skill."""
@pytest.mark.parametrize(
"alias",
@@ -1553,7 +1553,7 @@ class TestMCPSkillsSourceArchiveCollisions:
@pytest.mark.parametrize("alias_first", [False, True])
@pytest.mark.parametrize("identical", [False, True])
@pytest.mark.parametrize("with_digest", [False, True])
- async def test_colliding_resources_keep_first_file_and_warn(
+ async def test_colliding_resources_reject_skill_and_warn(
self, alias: str, alias_first: bool, identical: bool, with_digest: bool, caplog: pytest.LogCaptureFixture
) -> None:
url = "skill://archives/packaged-skill.zip"
@@ -1572,24 +1572,15 @@ async def test_colliding_resources_keep_first_file_and_warn(
for _ in range(2):
skills = await source.get_skills(_SOURCE_CTX)
- assert len(skills) == 1
- for resource_name in ("refs/policy.md", "REFS/POLICY.MD"):
- resource = await skills[0].get_resource(resource_name)
- assert resource is not None
- assert await resource.read() == "First resource."
- other = await skills[0].get_resource("refs/other.md")
- assert other is not None
- assert await other.read() == "Unaffected resource."
-
- collisions = [record for record in caplog.records if "duplicate archive member" in record.getMessage()]
- assert len(collisions) == 2
- assert all(record.levelname == "WARNING" for record in collisions)
- assert all("keeping the first file" in record.getMessage() for record in collisions)
- assert all("Substituted resource." not in record.getMessage() for record in collisions)
-
- @pytest.mark.parametrize("alias", ["SKILL.md", ".//SKILL.md", "/SKILL.md", "skill.md", "Skill.MD"])
+ assert skills == []
+
+ warnings = [record for record in caplog.records if record.levelname == "WARNING"]
+ assert len(warnings) == 2
+ assert all("'packaged-skill'" in record.getMessage() for record in warnings)
+
+ @pytest.mark.parametrize("alias", [".//SKILL.md", "/SKILL.md"])
@pytest.mark.parametrize("alias_first", [False, True])
- async def test_colliding_skill_md_keeps_first_file_and_warns(
+ async def test_duplicate_skill_md_rejects_skill_and_warns(
self, alias: str, alias_first: bool, caplog: pytest.LogCaptureFixture
) -> None:
url = "skill://archives/packaged-skill.zip"
@@ -1605,28 +1596,103 @@ async def test_colliding_skill_md_keeps_first_file_and_warns(
_SOURCE_CTX
)
- assert len(skills) == 1
- assert skills[0].frontmatter.name == "packaged-skill"
- assert "Instructions from an archive." in await skills[0].get_content()
+ assert skills == []
assert len(caplog.records) == 1
assert caplog.records[0].levelname == "WARNING"
- assert "duplicate archive member" in caplog.text
+ assert "Failed to extract archive" in caplog.text
+
+ @pytest.mark.parametrize(
+ ("manifest", "variant"),
+ [
+ ("SKILL.md", "skill.md"),
+ ("SKILL.md", "Skill.MD"),
+ ("nested/SKILL.md", "nested/skill.md"),
+ ("nested/SKILL.md", "NESTED/SKILL.md"),
+ ],
+ )
+ @pytest.mark.parametrize("variant_first", [False, True])
+ async def test_case_variant_manifests_skip_only_affected_skill(
+ self, manifest: str, variant: str, variant_first: bool, caplog: pytest.LogCaptureFixture
+ ) -> None:
+ url = "skill://archives/packaged-skill.zip"
+ manifests = [
+ (manifest, ARCHIVE_SKILL_MD.encode()),
+ (variant, ARCHIVE_SKILL_MD.replace("Instructions from an archive.", "Other instructions.").encode()),
+ ]
+ if variant_first:
+ manifests.reverse()
+ archive = _make_zip(manifests)
+ index_data = json.loads(SAMPLE_SKILL_INDEX)
+ index_data["skills"].extend(json.loads(_make_archive_index("packaged-skill", url))["skills"])
+ client = _archive_client(json.dumps(index_data), url, archive, "application/zip")
+
+ skills = await MCPSkillsSource(client=client).get_skills(_SOURCE_CTX)
+
+ assert [skill.frontmatter.name for skill in skills] == ["unit-converter"]
+ assert len(caplog.records) == 1
+ assert caplog.records[0].levelname == "WARNING"
+ assert "'packaged-skill'" in caplog.text
+ assert "SKILL.md paths that differ only by case" in caplog.text
+
+ @pytest.mark.parametrize(
+ ("manifest", "other"),
+ [("SKILL.md", "nested/skill.md"), ("a/SKILL.md", "b/skill.md")],
+ )
+ async def test_manifests_in_distinct_directories_are_not_case_variants(self, manifest: str, other: str) -> None:
+ url = "skill://archives/packaged-skill.zip"
+ archive = _make_zip([
+ (manifest, ARCHIVE_SKILL_MD.encode()),
+ (other, ARCHIVE_SKILL_MD.encode()),
+ ])
+ index = _make_archive_index("packaged-skill", url)
+
+ skills = await MCPSkillsSource(client=_archive_client(index, url, archive, "application/zip")).get_skills(
+ _SOURCE_CTX
+ )
+
+ assert [skill.frontmatter.name for skill in skills] == ["packaged-skill"]
- async def test_collision_does_not_skip_other_skills(self, caplog: pytest.LogCaptureFixture) -> None:
+ @pytest.mark.parametrize("duplicate", ["./reference.md", "REFERENCE.md"])
+ async def test_collision_does_not_skip_other_skills(self, duplicate: str, caplog: pytest.LogCaptureFixture) -> None:
url = "skill://archives/packaged-skill.zip"
index_data = json.loads(SAMPLE_SKILL_INDEX)
index_data["skills"].extend(json.loads(_make_archive_index("packaged-skill", url))["skills"])
archive = _make_zip([
("SKILL.md", ARCHIVE_SKILL_MD.encode()),
("reference.md", b"First."),
- ("./reference.md", b"Second."),
+ (duplicate, b"Second."),
])
client = _archive_client(json.dumps(index_data), url, archive, "application/zip")
skills = await MCPSkillsSource(client=client).get_skills(_SOURCE_CTX)
- assert sorted(skill.frontmatter.name for skill in skills) == ["packaged-skill", "unit-converter"]
- assert "duplicate archive member" in caplog.text
+ assert [skill.frontmatter.name for skill in skills] == ["unit-converter"]
+ assert "'packaged-skill'" in caplog.text
+
+ async def test_distinct_resource_paths_load_with_case_insensitive_lookup(self) -> None:
+ url = "skill://archives/packaged-skill.zip"
+ archive = _make_zip([
+ ("SKILL.md", ARCHIVE_SKILL_MD.encode()),
+ ("reference.md", b"Root resource."),
+ ("REFERENCE.MD/nested.md", b"Nested resource."),
+ ("refs/one.md", b"One."),
+ ("REFS/two.md", b"Two."),
+ ])
+ index = _make_archive_index("packaged-skill", url)
+ skills = await MCPSkillsSource(client=_archive_client(index, url, archive, "application/zip")).get_skills(
+ _SOURCE_CTX
+ )
+
+ assert len(skills) == 1
+ for name, content in (
+ ("REFERENCE.MD", "Root resource."),
+ ("reference.md/NESTED.MD", "Nested resource."),
+ ("REFS/ONE.MD", "One."),
+ ("refs/two.md", "Two."),
+ ):
+ resource = await skills[0].get_resource(name)
+ assert resource is not None
+ assert await resource.read() == content
class TestMCPSkillsSourceArchiveDigest:
@@ -1941,30 +2007,20 @@ def test_duplicate_members_count_toward_file_limit(self) -> None:
with pytest.raises(ValueError, match="file count"):
_extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 1, 1024 * 1024)
- def test_skipped_duplicate_is_not_decompressed(self, caplog: pytest.LogCaptureFixture) -> None:
- from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory, _read_member_with_limit
-
- archive = _make_zip([("reference.md", b"First."), ("./reference.md", b"x" * 100)])
- with patch("agent_framework._skills._read_member_with_limit", wraps=_read_member_with_limit) as read:
- files = _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, len(b"First."))
+ def test_duplicate_normalized_path_rejects_archive(self) -> None:
+ from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory
- assert files == {"reference.md": b"First."}
- read.assert_called_once()
- assert "duplicate archive member" in caplog.text
+ archive = _make_zip([("reference.md", b"First."), ("./reference.md", b"Second.")])
+ with pytest.raises(ValueError, match="Duplicate archive member"):
+ _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, 1024 * 1024)
- @pytest.mark.parametrize("first_name", ["reference.md", "REFERENCE.md"])
- def test_case_collision_keeps_first_name_and_warns(self, first_name: str, caplog: pytest.LogCaptureFixture) -> None:
+ def test_case_variants_are_extracted_as_is(self) -> None:
from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory
- second_name = "REFERENCE.md" if first_name == "reference.md" else "reference.md"
- archive = _make_zip([(first_name, b"First."), (second_name, b"Second.")])
-
- files = _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, 1024 * 1024)
+ entries = {"reference.md": b"First.", "REFERENCE.md": b"Second."}
+ files = _extract_archive_to_memory(_make_zip(entries), _ArchiveFormat.ZIP, 20, 1024 * 1024)
- assert files == {first_name: b"First."}
- assert len(caplog.records) == 1
- assert caplog.records[0].levelname == "WARNING"
- assert "duplicate archive member" in caplog.text
+ assert files == entries
def test_distinct_lowercase_resource_names_are_preserved(self, caplog: pytest.LogCaptureFixture) -> None:
from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory
diff --git a/python/packages/core/tests/core/test_skills.py b/python/packages/core/tests/core/test_skills.py
index 944c7d74a18..bfb3e63d12e 100644
--- a/python/packages/core/tests/core/test_skills.py
+++ b/python/packages/core/tests/core/test_skills.py
@@ -2583,6 +2583,86 @@ async def test_resources_populated(self, tmp_path: Path) -> None:
# ---------------------------------------------------------------------------
+class TestFileSkillNameCollisions:
+ @pytest.mark.parametrize("kind", ["resource", "script"])
+ @pytest.mark.parametrize("names", [("readme.md", "README.md"), ("refs/one.md", "REFS/ONE.md")])
+ @pytest.mark.parametrize("reverse", [False, True])
+ def test_constructor_rejects_names_differing_only_by_case(
+ self, kind: str, names: tuple[str, str], reverse: bool
+ ) -> None:
+ names = (names[1], names[0]) if reverse else names
+ resources = [InlineSkillResource(name=name, content="data") for name in names]
+ scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names]
+ with pytest.raises(ValueError, match=f"{kind} names that differ only by case"):
+ FileSkill(
+ frontmatter=SkillFrontmatter(name="example", description="Example."),
+ content="Instructions.",
+ path=_ABS,
+ resources=resources if kind == "resource" else [],
+ scripts=scripts if kind == "script" else [],
+ )
+
+ async def test_resource_and_script_names_are_checked_separately(self) -> None:
+ resource = InlineSkillResource(name="run.py", content="data")
+ script = FileSkillScript(name="RUN.py", full_path=f"{_ABS}\\RUN.py")
+ skill = FileSkill(
+ frontmatter=SkillFrontmatter(name="example", description="Example."),
+ content="Instructions.",
+ path=_ABS,
+ resources=[resource],
+ scripts=[script],
+ )
+ assert await skill.get_resource("RUN.PY") is resource
+ assert await skill.get_script("run.py") is script
+
+ @pytest.mark.parametrize("names", [("\u03a3.md", "\u03c2.md"), ("stra\u00dfe.md", "strasse.md")])
+ async def test_unicode_names_with_distinct_lowercase_keys_remain_distinct(self, names: tuple[str, str]) -> None:
+ resources = [InlineSkillResource(name=name, content=name) for name in names]
+ scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names]
+ skill = FileSkill(
+ frontmatter=SkillFrontmatter(name="example", description="Example."),
+ content="Instructions.",
+ path=_ABS,
+ resources=resources,
+ scripts=scripts,
+ )
+
+ for resource, script in zip(resources, scripts):
+ assert await skill.get_resource(resource.name.lower()) is resource
+ assert await skill.get_script(script.name.lower()) is script
+
+ async def test_distinct_names_allow_case_insensitive_lookup(self) -> None:
+ names = ["readme.md", "refs/one.md", "REFS/two.md"]
+ resources = [InlineSkillResource(name=name, content=name) for name in names]
+ scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names]
+ skill = FileSkill(
+ frontmatter=SkillFrontmatter(name="example", description="Example."),
+ content="Instructions.",
+ path=_ABS,
+ resources=resources,
+ scripts=scripts,
+ )
+ for resource, script in zip(resources, scripts):
+ assert await skill.get_resource(resource.name.upper()) is resource
+ assert await skill.get_script(script.name.upper()) is script
+
+ async def test_filesystem_collision_skips_only_affected_skill(
+ self, tmp_path: Path, caplog: pytest.LogCaptureFixture
+ ) -> None:
+ _write_skill(tmp_path, "bad")
+ _write_skill(tmp_path, "good")
+ original = FileSkillsSource._discover_script_files
+
+ def discover_script_files(self: FileSkillsSource, skill_path: str, skill_name: str) -> list[str]:
+ return ["run.py", "RUN.py"] if skill_name == "bad" else original(self, skill_path, skill_name)
+
+ with patch.object(FileSkillsSource, "_discover_script_files", discover_script_files):
+ skills = await FileSkillsSource(tmp_path).get_skills(_SOURCE_CTX)
+
+ assert [skill.frontmatter.name for skill in skills] == ["good"]
+ assert "Skipping skill 'bad'" in caplog.text
+
+
class TestLoadSkillFormatting:
"""Tests for _load_skill output formatting differences between file-based and code-defined skills."""