agentskills-azure 0.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,112 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentskills-azure
3
+ Version: 0.8.0
4
+ Summary: Azure-backed providers for the Agent Skills format (https://agentskills.io)
5
+ License: MIT
6
+ Author: Pratik Panda
7
+ Requires-Python: >=3.12,<4.0
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Programming Language :: Python :: 3.15
16
+ Classifier: Topic :: Software Development :: Libraries
17
+ Provides-Extra: blob
18
+ Provides-Extra: files
19
+ Requires-Dist: agentskills-core (>=0.8.0,<1.0)
20
+ Requires-Dist: azure-identity (>=1.19,<2.0)
21
+ Requires-Dist: azure-storage-blob[aio] (>=12.23,<13.0) ; extra == "blob"
22
+ Requires-Dist: azure-storage-file-share[aio] (>=12.23,<13.0) ; extra == "files"
23
+ Project-URL: Homepage, https://agentskills.io
24
+ Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
25
+ Description-Content-Type: text/markdown
26
+
27
+ ---
28
+ title: agentskills-azure
29
+ description: Azure-backed providers for Agent Skills with service-specific optional extras.
30
+ ---
31
+
32
+ Azure-backed skill providers share this package and use service-specific modules and
33
+ optional dependencies. Blob Storage is available through the `blob` extra.
34
+ Azure Files SMB shares are available through the `files` extra.
35
+
36
+ ## Install
37
+
38
+ ```bash
39
+ pip install "agentskills-azure[blob,files]"
40
+ ```
41
+
42
+ Install only `agentskills-azure[blob]` or `agentskills-azure[files]` when you need one service.
43
+
44
+ ## Blob Storage
45
+
46
+ Read Agent Skills from Azure Blob Storage with the asynchronous Azure SDK. The
47
+ provider uses `DefaultAzureCredential` by default, discovers skills from
48
+ `SKILL.md` blobs, and preserves original file bytes for complete manifests.
49
+ Each skill is a directory beneath the configured prefix, for example
50
+ `published/incident-response/SKILL.md`. Upload valid skill content before running the example.
51
+ Authenticate for local development with `az login`, or configure a managed identity in Azure.
52
+ Replace the account URL and container name with yours.
53
+
54
+ ```python
55
+ import asyncio
56
+
57
+ from agentskills_azure.blob import AzureBlobSkillProvider
58
+
59
+
60
+ async def main() -> None:
61
+ async with AzureBlobSkillProvider(
62
+ "https://account.blob.core.windows.net", "skills", prefix="published/"
63
+ ) as provider:
64
+ print(await provider.discover())
65
+ print(await provider.get_body("incident-response"))
66
+
67
+
68
+ asyncio.run(main())
69
+ ```
70
+
71
+ Pass an asynchronous Azure credential to `credential` when the application
72
+ manages authentication itself. Assign the identity only the blob permissions
73
+ needed to read the selected container.
74
+
75
+ ## Azure Files
76
+
77
+ Use the async FileREST SDK to read skill directories from an SMB share without mounting it:
78
+ create the share and upload `published/incident-response/SKILL.md` first. The same Azure
79
+ credential-chain setup applies, but FileREST token authentication has different permissions.
80
+
81
+ ```python
82
+ import asyncio
83
+
84
+ from agentskills_azure.files import AzureFilesSkillProvider
85
+
86
+
87
+ async def main() -> None:
88
+ async with AzureFilesSkillProvider(
89
+ "https://account.file.core.windows.net",
90
+ "skills",
91
+ prefix="published/",
92
+ token_intent="backup",
93
+ ) as provider:
94
+ print(await provider.discover())
95
+ print(await provider.read_file("incident-response", "SKILL.md"))
96
+
97
+
98
+ asyncio.run(main())
99
+ ```
100
+
101
+ Token authentication requires the explicit `token_intent="backup"` opt-in. FileREST backup
102
+ intent bypasses file and directory ACLs, subject to Azure RBAC permissions. Assign the identity
103
+ only the required backup-read permissions at the narrowest applicable scope.
104
+
105
+ Discovery and listing read metadata without downloading file contents. Reads preserve original
106
+ bytes, disable automatic decompression, and enforce `max_file_bytes`. Recursive listing is bounded
107
+ by `max_files` and `max_depth`. NFS shares and reparse points are rejected.
108
+
109
+ Both providers close owned clients and default credentials. Caller-supplied async credentials
110
+ remain caller-owned. Fake-client conformance tests do not certify a production identity or share
111
+ configuration.
112
+
@@ -0,0 +1,85 @@
1
+ ---
2
+ title: agentskills-azure
3
+ description: Azure-backed providers for Agent Skills with service-specific optional extras.
4
+ ---
5
+
6
+ Azure-backed skill providers share this package and use service-specific modules and
7
+ optional dependencies. Blob Storage is available through the `blob` extra.
8
+ Azure Files SMB shares are available through the `files` extra.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ pip install "agentskills-azure[blob,files]"
14
+ ```
15
+
16
+ Install only `agentskills-azure[blob]` or `agentskills-azure[files]` when you need one service.
17
+
18
+ ## Blob Storage
19
+
20
+ Read Agent Skills from Azure Blob Storage with the asynchronous Azure SDK. The
21
+ provider uses `DefaultAzureCredential` by default, discovers skills from
22
+ `SKILL.md` blobs, and preserves original file bytes for complete manifests.
23
+ Each skill is a directory beneath the configured prefix, for example
24
+ `published/incident-response/SKILL.md`. Upload valid skill content before running the example.
25
+ Authenticate for local development with `az login`, or configure a managed identity in Azure.
26
+ Replace the account URL and container name with yours.
27
+
28
+ ```python
29
+ import asyncio
30
+
31
+ from agentskills_azure.blob import AzureBlobSkillProvider
32
+
33
+
34
+ async def main() -> None:
35
+ async with AzureBlobSkillProvider(
36
+ "https://account.blob.core.windows.net", "skills", prefix="published/"
37
+ ) as provider:
38
+ print(await provider.discover())
39
+ print(await provider.get_body("incident-response"))
40
+
41
+
42
+ asyncio.run(main())
43
+ ```
44
+
45
+ Pass an asynchronous Azure credential to `credential` when the application
46
+ manages authentication itself. Assign the identity only the blob permissions
47
+ needed to read the selected container.
48
+
49
+ ## Azure Files
50
+
51
+ Use the async FileREST SDK to read skill directories from an SMB share without mounting it:
52
+ create the share and upload `published/incident-response/SKILL.md` first. The same Azure
53
+ credential-chain setup applies, but FileREST token authentication has different permissions.
54
+
55
+ ```python
56
+ import asyncio
57
+
58
+ from agentskills_azure.files import AzureFilesSkillProvider
59
+
60
+
61
+ async def main() -> None:
62
+ async with AzureFilesSkillProvider(
63
+ "https://account.file.core.windows.net",
64
+ "skills",
65
+ prefix="published/",
66
+ token_intent="backup",
67
+ ) as provider:
68
+ print(await provider.discover())
69
+ print(await provider.read_file("incident-response", "SKILL.md"))
70
+
71
+
72
+ asyncio.run(main())
73
+ ```
74
+
75
+ Token authentication requires the explicit `token_intent="backup"` opt-in. FileREST backup
76
+ intent bypasses file and directory ACLs, subject to Azure RBAC permissions. Assign the identity
77
+ only the required backup-read permissions at the narrowest applicable scope.
78
+
79
+ Discovery and listing read metadata without downloading file contents. Reads preserve original
80
+ bytes, disable automatic decompression, and enforce `max_file_bytes`. Recursive listing is bounded
81
+ by `max_files` and `max_depth`. NFS shares and reparse points are rejected.
82
+
83
+ Both providers close owned clients and default credentials. Caller-supplied async credentials
84
+ remain caller-owned. Fake-client conformance tests do not certify a production identity or share
85
+ configuration.
@@ -0,0 +1 @@
1
+ """Azure-backed Agent Skills providers with provider-specific optional extras."""
@@ -0,0 +1,215 @@
1
+ """Azure Blob Storage-backed Agent Skills provider."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import PurePosixPath
6
+ from typing import Any
7
+
8
+ from azure.core.credentials_async import AsyncTokenCredential
9
+ from azure.core.exceptions import AzureError
10
+ from azure.core.exceptions import ResourceNotFoundError as AzureResourceNotFoundError
11
+ from azure.identity.aio import DefaultAzureCredential
12
+
13
+ from agentskills_core import (
14
+ RESOURCE_KINDS,
15
+ AgentSkillsError,
16
+ ResourceNotFoundError,
17
+ SkillNotFoundError,
18
+ SkillProvider,
19
+ split_frontmatter,
20
+ )
21
+
22
+ try:
23
+ from azure.storage.blob.aio import BlobServiceClient
24
+ except ModuleNotFoundError as exc:
25
+ raise ImportError("Install 'agentskills-azure[blob]' to use AzureBlobSkillProvider.") from exc
26
+
27
+ DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024
28
+ SKILL_FILE_NAME = "SKILL.md"
29
+
30
+
31
+ class AzureBlobSkillProvider(SkillProvider):
32
+ """Read and discover skills stored as blobs beneath a container prefix.
33
+
34
+ A skill is a virtual directory containing ``SKILL.md`` and optional files.
35
+ The provider uses the Azure SDK's asynchronous clients and defaults to
36
+ ``DefaultAzureCredential``. Call :meth:`aclose` when finished, or use the
37
+ provider as an asynchronous context manager.
38
+
39
+ Args:
40
+ account_url: Blob service endpoint, such as ``https://account.blob.core.windows.net``.
41
+ container_name: Container holding the skill blobs.
42
+ prefix: Optional path prefix inside the container.
43
+ credential: Optional asynchronous Azure credential. When omitted, the
44
+ provider creates and owns a ``DefaultAzureCredential``.
45
+ max_file_bytes: Maximum size of any file read by the provider.
46
+
47
+ Raises:
48
+ ValueError: If the container name, prefix, or size limit is invalid.
49
+ """
50
+
51
+ supports_discovery = True
52
+ supports_resource_listing = True
53
+ supports_file_access = True
54
+
55
+ def __init__(
56
+ self,
57
+ account_url: str,
58
+ container_name: str,
59
+ *,
60
+ prefix: str = "",
61
+ credential: AsyncTokenCredential | None = None,
62
+ max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
63
+ ) -> None:
64
+ if not container_name or "/" in container_name or "\\" in container_name:
65
+ raise ValueError("container_name must be a non-empty container name")
66
+ if max_file_bytes < 0:
67
+ raise ValueError("max_file_bytes must be non-negative")
68
+ self._prefix = self._normalize_prefix(prefix)
69
+ self._max_file_bytes = max_file_bytes
70
+ self._owns_credential = credential is None
71
+ self._credential = credential or DefaultAzureCredential()
72
+ self._service = BlobServiceClient(account_url, credential=self._credential)
73
+ self._container = self._service.get_container_client(container_name)
74
+
75
+ async def __aenter__(self) -> AzureBlobSkillProvider:
76
+ return self
77
+
78
+ async def __aexit__(self, *_: object) -> None:
79
+ await self.aclose()
80
+
81
+ async def aclose(self) -> None:
82
+ """Close the Blob service client and any credential created by this provider."""
83
+ await self._service.close()
84
+ if self._owns_credential:
85
+ await self._credential.close()
86
+
87
+ async def discover(self) -> list[str]:
88
+ """List skill IDs with a top-level ``SKILL.md`` blob."""
89
+ skill_ids: set[str] = set()
90
+ async for blob in self._container.list_blobs(name_starts_with=self._prefix or None):
91
+ relative = blob.name[len(self._prefix) :]
92
+ parts = relative.split("/")
93
+ if len(parts) == 2 and parts[1] == SKILL_FILE_NAME and self._valid_segment(parts[0]):
94
+ skill_ids.add(parts[0])
95
+ return sorted(skill_ids)
96
+
97
+ async def get_metadata(self, skill_id: str) -> dict[str, Any]:
98
+ """Parse and return a skill's YAML frontmatter."""
99
+ raw = await self._read_skill_md(skill_id)
100
+ metadata, _ = split_frontmatter(raw)
101
+ return metadata
102
+
103
+ async def get_body(self, skill_id: str) -> str:
104
+ """Return the Markdown body after a skill's YAML frontmatter."""
105
+ raw = await self._read_skill_md(skill_id)
106
+ _, body = split_frontmatter(raw)
107
+ return body
108
+
109
+ async def get_script(self, skill_id: str, name: str) -> bytes:
110
+ """Read one script as raw bytes."""
111
+ return await self.read_file(skill_id, f"scripts/{name}")
112
+
113
+ async def get_asset(self, skill_id: str, name: str) -> bytes:
114
+ """Read one asset as raw bytes."""
115
+ return await self.read_file(skill_id, f"assets/{name}")
116
+
117
+ async def get_reference(self, skill_id: str, name: str) -> bytes:
118
+ """Read one reference as raw bytes."""
119
+ return await self.read_file(skill_id, f"references/{name}")
120
+
121
+ async def list_resources(self, skill_id: str) -> dict[str, list[str]]:
122
+ """List direct files in the standard resource directories."""
123
+ paths = await self.list_files(skill_id)
124
+ resources = {kind: [] for kind in RESOURCE_KINDS}
125
+ for path in paths:
126
+ parts = path.split("/")
127
+ if len(parts) == 2 and parts[0] in resources:
128
+ resources[parts[0]].append(parts[1])
129
+ return {kind: sorted(names) for kind, names in resources.items()}
130
+
131
+ async def list_files(self, skill_id: str) -> list[str]:
132
+ """List all file paths in a skill without downloading their contents."""
133
+ prefix = self._skill_prefix(skill_id)
134
+ files: list[str] = []
135
+ async for blob in self._container.list_blobs(name_starts_with=prefix):
136
+ relative = blob.name[len(prefix) :]
137
+ if relative and not relative.endswith("/"):
138
+ self._validate_relative_path(relative)
139
+ files.append(relative)
140
+ if SKILL_FILE_NAME not in files:
141
+ raise SkillNotFoundError(f"Skill not found: {skill_id!r}")
142
+ return sorted(files)
143
+
144
+ async def read_file(self, skill_id: str, path: str) -> bytes:
145
+ """Read a complete file as original bytes, without newline conversion."""
146
+ relative = self._validate_relative_path(path)
147
+ blob_name = f"{self._skill_prefix(skill_id)}{relative}"
148
+ blob = self._container.get_blob_client(blob_name)
149
+ try:
150
+ properties = await blob.get_blob_properties()
151
+ if properties.size > self._max_file_bytes:
152
+ raise AgentSkillsError(
153
+ f"File exceeds the {self._max_file_bytes}-byte limit: {relative}"
154
+ )
155
+ chunks: list[bytes] = []
156
+ size = 0
157
+ async for chunk in (await blob.download_blob()).chunks():
158
+ size += len(chunk)
159
+ if size > self._max_file_bytes:
160
+ raise AgentSkillsError(
161
+ f"File exceeds the {self._max_file_bytes}-byte limit: {relative}"
162
+ )
163
+ chunks.append(chunk)
164
+ content = b"".join(chunks)
165
+ except AzureResourceNotFoundError as exc:
166
+ raise ResourceNotFoundError(f"File not found: {skill_id}/{relative}") from exc
167
+ except AzureError as exc:
168
+ raise AgentSkillsError("Azure Blob Storage request failed") from exc
169
+ if len(content) > self._max_file_bytes:
170
+ raise AgentSkillsError(
171
+ f"File exceeds the {self._max_file_bytes}-byte limit: {relative}"
172
+ )
173
+ return content
174
+
175
+ async def _read_skill_md(self, skill_id: str) -> str:
176
+ try:
177
+ return (await self.read_file(skill_id, SKILL_FILE_NAME)).decode("utf-8")
178
+ except ResourceNotFoundError as exc:
179
+ raise SkillNotFoundError(f"Skill not found: {skill_id!r}") from exc
180
+ except UnicodeDecodeError as exc:
181
+ raise AgentSkillsError(f"SKILL.md must contain UTF-8 text: {skill_id!r}") from exc
182
+
183
+ def _skill_prefix(self, skill_id: str) -> str:
184
+ if not self._valid_segment(skill_id):
185
+ raise SkillNotFoundError(f"Invalid skill ID: {skill_id!r}")
186
+ return f"{self._prefix}{skill_id}/"
187
+
188
+ @staticmethod
189
+ def _normalize_prefix(prefix: str) -> str:
190
+ if not prefix:
191
+ return ""
192
+ candidate = prefix[:-1] if prefix.endswith("/") else prefix
193
+ path = AzureBlobSkillProvider._validate_relative_path(candidate)
194
+ return f"{path}/"
195
+
196
+ @staticmethod
197
+ def _valid_segment(value: str) -> bool:
198
+ return (
199
+ bool(value)
200
+ and value not in {".", ".."}
201
+ and not any(char in value for char in "/\\\x00")
202
+ )
203
+
204
+ @staticmethod
205
+ def _validate_relative_path(path: str) -> str:
206
+ candidate = PurePosixPath(path)
207
+ if (
208
+ not path
209
+ or "\\" in path
210
+ or "\x00" in path
211
+ or candidate.is_absolute()
212
+ or any(part in {"", ".", ".."} for part in path.split("/"))
213
+ ):
214
+ raise ResourceNotFoundError(f"Invalid skill file path: {path!r}")
215
+ return candidate.as_posix()
@@ -0,0 +1,274 @@
1
+ """Azure Files-backed Agent Skills provider."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import PurePosixPath
6
+ from typing import Any, Literal
7
+
8
+ from azure.core.credentials_async import AsyncTokenCredential
9
+ from azure.core.exceptions import AzureError
10
+ from azure.core.exceptions import ResourceNotFoundError as AzureResourceNotFoundError
11
+ from azure.identity.aio import DefaultAzureCredential
12
+
13
+ from agentskills_core import (
14
+ RESOURCE_KINDS,
15
+ AgentSkillsError,
16
+ ResourceNotFoundError,
17
+ SkillNotFoundError,
18
+ SkillProvider,
19
+ split_frontmatter,
20
+ )
21
+
22
+ try:
23
+ from azure.storage.fileshare.aio import ShareClient, ShareDirectoryClient
24
+ except ModuleNotFoundError as exc:
25
+ raise ImportError("Install 'agentskills-azure[files]' to use AzureFilesSkillProvider.") from exc
26
+
27
+
28
+ class AzureFilesSkillProvider(SkillProvider):
29
+ """Read skills from directories in an Azure Files SMB share.
30
+
31
+ Uses the async FileREST SDK, not a mounted filesystem. Token authentication
32
+ requires an explicit ``token_intent="backup"`` opt-in because it bypasses
33
+ file ACLs subject to Azure RBAC. NFS shares and reparse points are rejected.
34
+
35
+ Args:
36
+ account_url: File service endpoint, such as ``https://account.file.core.windows.net``.
37
+ share_name: SMB share containing the skill directories.
38
+ prefix: Optional directory beneath which skills are stored.
39
+ credential: Caller-owned async credential. Defaults to an owned
40
+ ``DefaultAzureCredential``.
41
+ token_intent: Must be ``"backup"`` to acknowledge FileREST token semantics.
42
+ max_file_bytes: Maximum bytes returned by a file read.
43
+ max_files: Maximum files listed in one skill.
44
+ max_depth: Maximum nested directory depth inside one skill.
45
+
46
+ Raises:
47
+ ValueError: If the share, limits, or token intent are invalid.
48
+ ResourceNotFoundError: If the prefix contains an unsafe path.
49
+ """
50
+
51
+ supports_discovery = True
52
+ supports_resource_listing = True
53
+ supports_file_access = True
54
+
55
+ def __init__(
56
+ self,
57
+ account_url: str,
58
+ share_name: str,
59
+ *,
60
+ prefix: str = "",
61
+ credential: AsyncTokenCredential | None = None,
62
+ token_intent: Literal["backup"] | None = None,
63
+ max_file_bytes: int = 10 * 1024 * 1024,
64
+ max_files: int = 10_000,
65
+ max_depth: int = 64,
66
+ ) -> None:
67
+ if not self._valid_segment(share_name):
68
+ raise ValueError("share_name must be a non-empty share name")
69
+ if max_file_bytes < 0 or max_files < 1 or max_depth < 0:
70
+ raise ValueError(
71
+ "File size and depth limits must be non-negative and max_files positive"
72
+ )
73
+ if token_intent != "backup":
74
+ raise ValueError(
75
+ "Azure Files token credentials require token_intent='backup'; "
76
+ "this bypasses file ACLs and requires an authorized Azure RBAC role"
77
+ )
78
+ self._prefix = self._validate_path(prefix.removesuffix("/")) if prefix else ""
79
+ self._max_file_bytes = max_file_bytes
80
+ self._max_files = max_files
81
+ self._max_depth = max_depth
82
+ self._owns_credential = credential is None
83
+ self._credential = credential if credential is not None else DefaultAzureCredential()
84
+ self._share = ShareClient(
85
+ account_url,
86
+ share_name,
87
+ credential=self._credential,
88
+ token_intent=token_intent,
89
+ allow_trailing_dot=True,
90
+ )
91
+
92
+ async def __aenter__(self) -> AzureFilesSkillProvider:
93
+ return self
94
+
95
+ async def __aexit__(self, *_: object) -> None:
96
+ await self.aclose()
97
+
98
+ async def aclose(self) -> None:
99
+ """Close the share client and any provider-owned credential."""
100
+ try:
101
+ await self._share.close()
102
+ finally:
103
+ if self._owns_credential:
104
+ await self._credential.close()
105
+
106
+ async def discover(self) -> list[str]:
107
+ """Discover immediate skill directories using metadata only."""
108
+ skill_ids: list[str] = []
109
+ try:
110
+ root = await self._directory(self._prefix)
111
+ async for entry in root.list_directories_and_files(include=["Attributes"]):
112
+ if not entry.is_directory or not self._valid_segment(entry.name):
113
+ continue
114
+ self._reject_link(entry)
115
+ directory = root.get_subdirectory_client(entry.name)
116
+ self._reject_link(await directory.get_directory_properties())
117
+ try:
118
+ properties = await directory.get_file_client("SKILL.md").get_file_properties()
119
+ except AzureResourceNotFoundError:
120
+ continue
121
+ self._reject_link(properties)
122
+ skill_ids.append(entry.name)
123
+ except AzureError as exc:
124
+ raise AgentSkillsError("Azure Files discovery failed") from exc
125
+ return sorted(skill_ids)
126
+
127
+ async def get_metadata(self, skill_id: str) -> dict[str, Any]:
128
+ """Return the skill's YAML frontmatter."""
129
+ metadata, _ = split_frontmatter(await self._read_skill_md(skill_id))
130
+ return metadata
131
+
132
+ async def get_body(self, skill_id: str) -> str:
133
+ """Return the Markdown body after the frontmatter."""
134
+ _, body = split_frontmatter(await self._read_skill_md(skill_id))
135
+ return body
136
+
137
+ async def get_script(self, skill_id: str, name: str) -> bytes:
138
+ """Read one script without executing it."""
139
+ return await self.read_file(skill_id, f"scripts/{name}")
140
+
141
+ async def get_asset(self, skill_id: str, name: str) -> bytes:
142
+ """Read one asset as original bytes."""
143
+ return await self.read_file(skill_id, f"assets/{name}")
144
+
145
+ async def get_reference(self, skill_id: str, name: str) -> bytes:
146
+ """Read one reference as original bytes."""
147
+ return await self.read_file(skill_id, f"references/{name}")
148
+
149
+ async def list_resources(self, skill_id: str) -> dict[str, list[str]]:
150
+ """List direct files in the standard resource directories."""
151
+ resources = {kind: [] for kind in RESOURCE_KINDS}
152
+ for path in await self.list_files(skill_id):
153
+ parts = path.split("/")
154
+ if len(parts) == 2 and parts[0] in resources:
155
+ resources[parts[0]].append(parts[1])
156
+ return {kind: sorted(names) for kind, names in resources.items()}
157
+
158
+ async def list_files(self, skill_id: str) -> list[str]:
159
+ """List canonical files recursively without downloading their contents."""
160
+ root_path = self._skill_path(skill_id)
161
+ try:
162
+ root = await self._directory(root_path)
163
+ except AzureResourceNotFoundError as exc:
164
+ raise SkillNotFoundError(f"Skill not found: {skill_id!r}") from exc
165
+ except AzureError as exc:
166
+ raise AgentSkillsError("Azure Files listing failed") from exc
167
+ files: list[str] = []
168
+ pending = [(root, "", 0)]
169
+ directories = 0
170
+ try:
171
+ while pending:
172
+ directory, relative, depth = pending.pop()
173
+ async for entry in directory.list_directories_and_files(include=["Attributes"]):
174
+ if not self._valid_segment(entry.name):
175
+ raise ResourceNotFoundError("Invalid Azure Files directory entry")
176
+ self._reject_link(entry)
177
+ path = f"{relative}/{entry.name}" if relative else entry.name
178
+ if entry.is_directory:
179
+ directories += 1
180
+ if depth >= self._max_depth or directories > self._max_files:
181
+ raise AgentSkillsError("Azure Files directory traversal limit exceeded")
182
+ child = directory.get_subdirectory_client(entry.name)
183
+ self._reject_link(await child.get_directory_properties())
184
+ pending.append((child, path, depth + 1))
185
+ else:
186
+ files.append(path)
187
+ if len(files) > self._max_files:
188
+ raise AgentSkillsError("Azure Files file count limit exceeded")
189
+ except AzureResourceNotFoundError as exc:
190
+ raise ResourceNotFoundError("Azure Files directory disappeared during listing") from exc
191
+ except AzureError as exc:
192
+ raise AgentSkillsError("Azure Files listing failed") from exc
193
+ if "SKILL.md" not in files:
194
+ raise SkillNotFoundError(f"Skill not found: {skill_id!r}")
195
+ return sorted(files)
196
+
197
+ async def read_file(self, skill_id: str, path: str) -> bytes:
198
+ """Read original bytes with preflight and streamed size enforcement."""
199
+ relative = self._validate_path(path)
200
+ full_path = f"{self._skill_path(skill_id)}/{relative}"
201
+ parent, name = full_path.rsplit("/", 1)
202
+ try:
203
+ directory = await self._directory(parent)
204
+ file = directory.get_file_client(name)
205
+ properties = await file.get_file_properties()
206
+ self._reject_link(properties)
207
+ if properties.size > self._max_file_bytes:
208
+ raise AgentSkillsError(
209
+ f"File exceeds the {self._max_file_bytes}-byte limit: {path}"
210
+ )
211
+ chunks: list[bytes] = []
212
+ size = 0
213
+ async for chunk in (await file.download_file(decompress=False)).chunks():
214
+ size += len(chunk)
215
+ if size > self._max_file_bytes:
216
+ raise AgentSkillsError(
217
+ f"File exceeds the {self._max_file_bytes}-byte limit: {path}"
218
+ )
219
+ chunks.append(chunk)
220
+ return b"".join(chunks)
221
+ except AzureResourceNotFoundError as exc:
222
+ raise ResourceNotFoundError(f"File not found: {skill_id}/{relative}") from exc
223
+ except AzureError as exc:
224
+ raise AgentSkillsError("Azure Files read failed") from exc
225
+
226
+ async def _directory(self, path: str) -> ShareDirectoryClient:
227
+ properties = await self._share.get_share_properties()
228
+ if properties.protocols != "SMB":
229
+ raise AgentSkillsError("Only SMB Azure Files shares are supported")
230
+ directory = self._share.get_directory_client("")
231
+ self._reject_link(await directory.get_directory_properties())
232
+ for segment in path.split("/") if path else []:
233
+ directory = directory.get_subdirectory_client(segment)
234
+ self._reject_link(await directory.get_directory_properties())
235
+ return directory
236
+
237
+ async def _read_skill_md(self, skill_id: str) -> str:
238
+ try:
239
+ return (await self.read_file(skill_id, "SKILL.md")).decode("utf-8")
240
+ except ResourceNotFoundError as exc:
241
+ raise SkillNotFoundError(f"Skill not found: {skill_id!r}") from exc
242
+ except UnicodeDecodeError as exc:
243
+ raise AgentSkillsError(f"SKILL.md must contain UTF-8 text: {skill_id!r}") from exc
244
+
245
+ def _skill_path(self, skill_id: str) -> str:
246
+ if not self._valid_segment(skill_id):
247
+ raise SkillNotFoundError(f"Invalid skill ID: {skill_id!r}")
248
+ return f"{self._prefix}/{skill_id}" if self._prefix else skill_id
249
+
250
+ @staticmethod
251
+ def _reject_link(properties: Any) -> None:
252
+ if "reparsepoint" in (properties.file_attributes or "").lower().split("|"):
253
+ raise ResourceNotFoundError("Azure Files reparse points are not supported")
254
+
255
+ @staticmethod
256
+ def _valid_segment(value: str) -> bool:
257
+ return (
258
+ bool(value)
259
+ and value not in {".", ".."}
260
+ and not any(char in value for char in "/\\\x00")
261
+ )
262
+
263
+ @staticmethod
264
+ def _validate_path(path: str) -> str:
265
+ candidate = PurePosixPath(path)
266
+ if (
267
+ not path
268
+ or "\\" in path
269
+ or "\x00" in path
270
+ or candidate.is_absolute()
271
+ or any(part in {"", ".", ".."} for part in path.split("/"))
272
+ ):
273
+ raise ResourceNotFoundError(f"Invalid skill file path: {path!r}")
274
+ return candidate.as_posix()
@@ -0,0 +1 @@
1
+ # PEP 561 typed package.
@@ -0,0 +1,33 @@
1
+ [tool.poetry]
2
+ name = "agentskills-azure"
3
+ version = "0.8.0"
4
+ description = "Azure-backed providers for the Agent Skills format (https://agentskills.io)"
5
+ license = "MIT"
6
+ authors = ["Pratik Panda"]
7
+ readme = "README.md"
8
+ homepage = "https://agentskills.io"
9
+ repository = "https://github.com/pratikxpanda/agentskills-sdk"
10
+ packages = [{include = "agentskills_azure"}]
11
+ classifiers = [
12
+ "Development Status :: 3 - Alpha",
13
+ "Intended Audience :: Developers",
14
+ "Topic :: Software Development :: Libraries",
15
+ "Programming Language :: Python :: 3.12",
16
+ "Programming Language :: Python :: 3.13",
17
+ "Programming Language :: Python :: 3.14",
18
+ ]
19
+
20
+ [tool.poetry.dependencies]
21
+ python = ">=3.12,<4.0"
22
+ agentskills-core = ">=0.8.0,<1.0"
23
+ azure-identity = ">=1.19,<2.0"
24
+ azure-storage-blob = {version = ">=12.23,<13.0", extras = ["aio"], optional = true}
25
+ azure-storage-file-share = {version = ">=12.23,<13.0", extras = ["aio"], optional = true}
26
+
27
+ [tool.poetry.extras]
28
+ blob = ["azure-storage-blob"]
29
+ files = ["azure-storage-file-share"]
30
+
31
+ [build-system]
32
+ requires = ["poetry-core"]
33
+ build-backend = "poetry.core.masonry.api"