:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(skills): add resource manifest endpoints for mcp skills (#123182)
posthog[bot]9d29c7083546
diff --git a/docs/internal/skills/skill-md-api.md b/docs/internal/skills/skill-md-api.mdindex 7f12bb399280..fa9599b4c854 100644--- a/docs/internal/skills/skill-md-api.md+++ b/docs/internal/skills/skill-md-api.md@@ -58,3 +58,72 @@ Response:The spec has no top-level version field, so the platform version is parked under`metadata.version`. It is a string, and it changes on every publish even when the body does not,so the rendered file changes with it.++## Resource manifests++Two read endpoints return what an MCP server needs to answer `skills/get` and `skills/list`:+every file of a skill, with the SHA-256 and byte size of the exact bytes the store serves for it.+A host rejects a skill whose bytes disagree with the listing, so both endpoints read the digests the store stamped on write.+They never load the skill body or any file content.++Viewset: `products/skills/backend/api/skill_view_versions.py` (`manifest`) and `products/skills/backend/api/skills.py` (`manifests`).+Builder: `products/skills/backend/api/skill_manifest.py` (`build_skill_manifests`).++### One skill++```text+GET /api/projects/{team_id}/llm_skills/name/{skill_name}/manifest/?version=N+```++Same `version` handling, `llm_skill:read` scope, object access check and `403`/`404` rules as `skill-md`.+An unservable skill also returns `200`.++### Many skills++```text+GET /api/projects/{team_id}/llm_skills/manifests/?limit=&offset=&owner_id=&category=&exclude_category=+```++- The latest version of each skill, from the same access-filtered queryset and `limit`/`offset` pagination as the list.+- Takes the list filters (`search`, `created_by_id`, `owner_id`, `category`), plus `exclude_category` to leave one category out, for example `scout`.+- Weak `ETag`, `304` on `If-None-Match`, `X-Skills-Version`, private and no-cache headers, and the list throttles, all shared with the list.+- One query for the page of skills and one for all their file rows, whatever the page size.++### Entry shape++```json+{+ "name": "my-skill",+ "version": 3,+ "frontmatter": { "name": "my-skill", "description": "...", "metadata": { "version": "3" } },+ "resources": [+ { "path": "SKILL.md", "sha256": "<hex>", "size": 1234, "content_type": "text/markdown" },+ { "path": "references/guide.md", "sha256": "<hex>", "size": 567, "content_type": "text/markdown" }+ ],+ "file_count": 2,+ "total_size": 1801,+ "servable": true,+ "unservable_reasons": []+}+```++- `SKILL.md` comes first, then the bundled files sorted by `path`. The Codex sidecar `agents/openai.yaml` from zip export is not a resource.+- `frontmatter` equals the `frontmatter` of `skill-md` for the same version.+- `sha256` is bare hex. The MCP server adds the `sha256:` prefix and the `skill://` URI on the wire.+- `servable` is false when `unservable_reasons` holds any of these codes:++| Code | When |+| ---------------- | ---------------------------------------------------------------------------------------- |+| `too_many_files` | `file_count` is over `MCP_MAX_SKILL_FILES` (512), counting `SKILL.md`. |+| `too_large` | `total_size` is over `MCP_MAX_SKILL_BYTES` (16 MiB). |+| `digest_missing` | A stored digest or size is null, because the row predates the backfill. |+| `spec_problems` | `compute_spec_problems` reports a problem, the same check `spec_problems` shows authors. |++A null digest is not computed on read. The endpoint logs `llma_skill_manifest_digest_missing` with the skill names.+Run `backfill_skill_digests` before an MCP server serves skills from an environment.++### Keep the stored digests in step with the renderer++`skill_md_sha256` and `skill_md_size` are stamped from `render_skill_md` when a version is written.+A change to the renderer, including `frontmatter_document`, changes the served bytes of every existing skill.+Ship it with a run of `backfill_skill_digests --recompute`. Otherwise every manifest stops matching the bytes the store serves, and hosts ask every user to approve every skill again.diff --git a/products/skills/backend/api/skill_manifest.py b/products/skills/backend/api/skill_manifest.pynew file mode 100644index 000000000000..00e6fdfc87a5--- /dev/null+++ b/products/skills/backend/api/skill_manifest.py@@ -0,0 +1,116 @@+"""Resource manifests for the MCP Skills extension: every file a host downloads, with its digest.++A host verifies each file it reads against the SHA-256 and byte size the listing gave it, and+rejects the skill when they disagree. So the manifest reads the digests the store stamped on write+and never renders or loads content: a manifest that hashed on read could describe bytes the store+no longer serves.+"""++from collections.abc import Sequence+from uuid import UUID++from django.db import models++import structlog++from posthog.dataclasses import frozen++from ..marketplace.packaging import MCP_MAX_SKILL_BYTES, MCP_MAX_SKILL_FILES, frontmatter_document+from ..models.skills import LLMSkill, LLMSkillFile+from .skill_services import compute_spec_problems++logger = structlog.get_logger(__name__)++SKILL_MD_PATH = "SKILL.md"+SKILL_MD_CONTENT_TYPE = "text/markdown"+++class SkillUnservableReason(models.TextChoices):+ TOO_MANY_FILES = "too_many_files", "Too many files"+ TOO_LARGE = "too_large", "Too large"+ DIGEST_MISSING = "digest_missing", "Digest missing"+ SPEC_PROBLEMS = "spec_problems", "Spec problems"+++@frozen+class SkillManifestResource:+ path: str+ sha256: str | None+ size: int | None+ content_type: str+++@frozen+class SkillManifest:+ name: str+ version: int+ frontmatter: dict[str, object]+ resources: list[SkillManifestResource]+ file_count: int+ total_size: int+ servable: bool+ unservable_reasons: list[SkillUnservableReason]+++def build_skill_manifests(skills: Sequence[LLMSkill]) -> list[SkillManifest]:+ """One manifest per skill, in the order given, from one query for every bundled file row.++ The skills may be loaded with ``body`` deferred: nothing here reads it.+ """+ files_by_skill_id: dict[UUID, list[LLMSkillFile]] = {}+ file_rows = (+ LLMSkillFile.objects.filter(skill__in=skills)+ .only("skill_id", "path", "content_type", "content_size", "content_sha256")+ .order_by("path")+ )+ for file_row in file_rows:+ files_by_skill_id.setdefault(file_row.skill_id, []).append(file_row)++ manifests = [_build_manifest(skill, files_by_skill_id.get(skill.id, [])) for skill in skills]+ missing = [m.name for m in manifests if SkillUnservableReason.DIGEST_MISSING in m.unservable_reasons]+ if missing:+ logger.warning("llma_skill_manifest_digest_missing", skill_names=missing)+ return manifests+++def _build_manifest(skill: LLMSkill, files: list[LLMSkillFile]) -> SkillManifest:+ resources = [+ SkillManifestResource(+ path=SKILL_MD_PATH,+ sha256=skill.skill_md_sha256,+ size=skill.skill_md_size,+ content_type=SKILL_MD_CONTENT_TYPE,+ ),+ *(+ SkillManifestResource(+ path=file_row.path,+ sha256=file_row.content_sha256,+ size=file_row.content_size,+ content_type=file_row.content_type,+ )+ for file_row in files+ ),+ ]+ file_count = len(resources)+ total_size = sum(resource.size or 0 for resource in resources)++ reasons: list[SkillUnservableReason] = []+ if file_count > MCP_MAX_SKILL_FILES:+ reasons.append(SkillUnservableReason.TOO_MANY_FILES)+ if total_size > MCP_MAX_SKILL_BYTES:+ reasons.append(SkillUnservableReason.TOO_LARGE)+ if any(resource.sha256 is None or resource.size is None for resource in resources):+ reasons.append(SkillUnservableReason.DIGEST_MISSING)+ if compute_spec_problems(skill.name, skill.description, [file_row.path for file_row in files]):+ reasons.append(SkillUnservableReason.SPEC_PROBLEMS)++ return SkillManifest(+ name=skill.name,+ version=skill.version,+ frontmatter=frontmatter_document(skill.to_export(include_body=False)),+ resources=resources,+ file_count=file_count,+ total_size=total_size,+ servable=not reasons,+ unservable_reasons=reasons,+ )diff --git a/products/skills/backend/api/skill_serializers.py b/products/skills/backend/api/skill_serializers.pyindex 7075b9622dd0..85786f296a81 100644--- a/products/skills/backend/api/skill_serializers.py+++ b/products/skills/backend/api/skill_serializers.py@@ -13,7 +13,13 @@ from posthog.api.shared import UserBasicSerializerfrom products.ai_observability.backend.markdown_outline import get_markdown_outlinefrom ..activity_logging import log_skill_activity-from ..marketplace.packaging import DEFAULT_BUNDLE_SKILLS, MAX_BUNDLE_SKILLS, SPEC_DESCRIPTION_MAX_LENGTH+from ..marketplace.packaging import (+ DEFAULT_BUNDLE_SKILLS,+ MAX_BUNDLE_SKILLS,+ MCP_MAX_SKILL_BYTES,+ MCP_MAX_SKILL_FILES,+ SPEC_DESCRIPTION_MAX_LENGTH,+)from ..models.skills import MAX_SKILL_CATEGORY_LENGTH, LLMSkill, LLMSkillFile, category_for_skill_namefrom .community_publish_services import (DISPLAY_NAME_PATTERN,@@ -23,6 +29,7 @@ from .community_publish_services import (OPTIONAL_GITHUB_HANDLE_PATTERN,)from .community_skill_serializers import CommunitySkillScoutConfigSerializer+from .skill_manifest import SkillUnservableReasonfrom .skill_services import (MAX_SKILL_NAME_LENGTH,RESERVED_SKILL_NAMES,@@ -950,6 +957,59 @@ class LLMSkillMarkdownSerializer(serializers.Serializer):)+class LLMSkillManifestListQuerySerializer(LLMSkillListQuerySerializer):+ exclude_category = serializers.CharField(+ required=False,+ allow_blank=True,+ help_text='Leave out skills in this exact category, e.g. "scout" to skip Signals scouts. An empty string '+ "leaves out uncategorized skills.",+ )+++class LLMSkillManifestResourceSerializer(serializers.Serializer):+ path = serializers.CharField(+ help_text="Path of the file relative to the skill directory. SKILL.md for the rendered skill file."+ )+ sha256 = serializers.CharField(+ allow_null=True,+ help_text="Bare hex SHA-256 of the exact bytes served for this file, without a 'sha256:' prefix. "+ "Null on rows written before digests were stamped.",+ )+ size = serializers.IntegerField(+ allow_null=True,+ help_text="Byte length of the exact bytes served for this file, encoded as UTF-8. "+ "Null on rows written before digests were stamped.",+ )+ content_type = serializers.CharField(help_text="MIME type of the file, e.g. text/markdown.")+++class LLMSkillManifestSerializer(serializers.Serializer):+ name = serializers.CharField(help_text="Name of the skill, which is also its directory name.")+ version = serializers.IntegerField(help_text="Version of the skill that this manifest describes.")+ frontmatter = SkillFrontmatterField(+ help_text="The frontmatter of the served SKILL.md as a JSON object, equal to the frontmatter field of the "+ "skill-md endpoint for the same version."+ )+ resources = LLMSkillManifestResourceSerializer(+ many=True,+ help_text="Every file of the skill exactly once: SKILL.md first, then the bundled files sorted by path.",+ )+ file_count = serializers.IntegerField(help_text="Number of entries in resources, SKILL.md included.")+ total_size = serializers.IntegerField(+ help_text="Sum of every resource size in bytes. A resource with a null size counts as zero."+ )+ servable = serializers.BooleanField(+ help_text="Whether an MCP server may serve this skill. False when unservable_reasons is not empty."+ )+ unservable_reasons = serializers.ListField(+ child=serializers.ChoiceField(choices=SkillUnservableReason.choices),+ help_text="Why the skill must not be served, one code per reason. too_many_files: more than "+ f"{MCP_MAX_SKILL_FILES} files. too_large: more than {MCP_MAX_SKILL_BYTES} bytes in total. digest_missing: "+ "a stored digest or size is null. spec_problems: the skill fails the Agent Skills spec check, see "+ "spec_problems on the skill.",+ )++class LLMSkillFileCreateSerializer(LLMSkillFileInputSerializer):base_version = serializers.IntegerField(min_value=1,diff --git a/products/skills/backend/api/skill_services.py b/products/skills/backend/api/skill_services.pyindex 53d44a6cf45e..13e69aee6d39 100644--- a/products/skills/backend/api/skill_services.py+++ b/products/skills/backend/api/skill_services.py@@ -383,8 +383,11 @@ def get_skill_by_name_from_db(version_id: str | None = None,*,include_archived: bool = False,+ defer_body: bool = False,) -> LLMSkill | None:queryset = get_active_skill_queryset(team).filter(name=skill_name)+ if defer_body:+ queryset = queryset.defer("body")if version_id is not None:# `include_archived` honours a pin to one immutable version row even after@@ -395,6 +398,8 @@ def get_skill_by_name_from_db(if include_archivedelse queryset.filter(id=version_id))+ if defer_body:+ rows = rows.defer("body")if version is not None:rows = rows.filter(version=version)return rows.order_by("created_at", "id").first()diff --git a/products/skills/backend/api/skill_view_access.py b/products/skills/backend/api/skill_view_access.pyindex f9e03635c7de..a3630cdb177d 100644--- a/products/skills/backend/api/skill_view_access.py+++ b/products/skills/backend/api/skill_view_access.py@@ -76,9 +76,11 @@ class SkillAccessMixin(_SkillViewBase):skill_name: str,version: int | None = None,version_id: str | None = None,+ *,+ defer_body: bool = False,) -> LLMSkill | None:# has_permission passes anyone with a grant on any one skill, so the loaded row is checked here.- skill = get_skill_by_name_from_db(self.team, skill_name, version, version_id)+ skill = get_skill_by_name_from_db(self.team, skill_name, version, version_id, defer_body=defer_body)if skill is not None:self.check_object_permissions(request, skill)skill = self._apply_trial_skill(request, skill)diff --git a/products/skills/backend/api/skill_view_versions.py b/products/skills/backend/api/skill_view_versions.pyindex 5ea2b24d1964..6329769ff7d8 100644--- a/products/skills/backend/api/skill_view_versions.py+++ b/products/skills/backend/api/skill_view_versions.py@@ -20,11 +20,13 @@ from ..marketplace.packaging import frontmatter_document, render_skill_mdfrom ..models.skills import LLMSkillfrom .skill_analytics import publish_analytics_props, record_skill_eventfrom .skill_error_responses import skill_write_error_response, version_conflict_response+from .skill_manifest import build_skill_manifestsfrom .skill_serializers import (DEFAULT_BODY_PAGE_LENGTH,PUBLISH_CONTENT_FIELDS,LLMSkillBodyFetchQuerySerializer,LLMSkillFetchQuerySerializer,+ LLMSkillManifestSerializer,LLMSkillMarkdownSerializer,LLMSkillPublishSerializer,LLMSkillResolveQuerySerializer,@@ -319,3 +321,29 @@ class SkillVersionActionsMixin(SkillAccessMixin):})return Response(payload.data)++ @extend_schema(+ parameters=[LLMSkillFetchQuerySerializer],+ responses={200: LLMSkillManifestSerializer},+ )+ @action(+ methods=["GET"],+ detail=False,+ url_path=r"name/(?P<skill_name>[^/]+)/manifest",+ required_scopes=["llm_skill:read"],+ )+ @llma_track_latency("llma_skills_manifest")+ @monitor(feature=None, endpoint="llma_skills_manifest", method="GET")+ def manifest(self, request: Request, skill_name: str = "", **kwargs) -> Response:+ """Every file of one skill with the digest and size of the bytes the store serves for it.++ Answers an unservable skill with 200 too, so a caller can log why it skips the skill.+ """+ version_params = self._validated_query(LLMSkillFetchQuerySerializer, request)+ version = cast(int | None, version_params.get("version"))+ skill = self._load_skill_with_object_access(request, skill_name, version, defer_body=True)+ if skill is None:+ return self._skill_not_found_response(skill_name, version)++ (manifest,) = build_skill_manifests([skill])+ return Response(LLMSkillManifestSerializer(instance=manifest).data)diff --git a/products/skills/backend/api/skills.py b/products/skills/backend/api/skills.pyindex ca5bac4abaff..898636de8189 100644--- a/products/skills/backend/api/skills.py+++ b/products/skills/backend/api/skills.py@@ -39,12 +39,15 @@ from products.ai_observability.backend.api.metrics import llma_track_latencyfrom ..models.skills import LLMSkill, LLMSkillFilefrom .skill_analytics import record_skill_event, skill_analytics_propsfrom .skill_catalog import list_queryset+from .skill_manifest import build_skill_manifestsfrom .skill_permissions import CommunityPublishFeatureFlagPermission, CommunityPublishOwnerPermissionfrom .skill_search import SkillSearchTimeout, search_skillsfrom .skill_serializers import (LLMSkillCreateSerializer,LLMSkillListQuerySerializer,LLMSkillListSerializer,+ LLMSkillManifestListQuerySerializer,+ LLMSkillManifestSerializer,LLMSkillSearchErrorSerializer,LLMSkillSearchQuerySerializer,LLMSkillSearchResponseSerializer,@@ -113,9 +116,9 @@ class LLMSkillViewSet(return [SkillBundleBurstThrottle(), SkillBundleSustainedThrottle()]if self.action == "search":return [SkillSearchBurstThrottle(), SkillSearchSustainedThrottle()]- if self.action == "list":+ if self.action in ["list", "manifests"]:return [SkillListBurstThrottle(), SkillListSustainedThrottle()]- if self.action in ["update_by_name", "get_by_name", "resolve_by_name"]:+ if self.action in ["update_by_name", "get_by_name", "resolve_by_name", "manifest"]:return [BurstRateThrottle(), SustainedRateThrottle()]return super().get_throttles()@@ -222,7 +225,46 @@ class LLMSkillViewSet(@monitor(feature=None, endpoint="llma_skills_list", method="GET")def list(self, request: Request, *args, **kwargs) -> HttpResponseBase:version = team_skills_version(self.team)- list_response = self._list_response(request)+ return self._conditional_list_response(request, self._list_response(request), version)++ @extend_schema(+ parameters=[LLMSkillManifestListQuerySerializer],+ responses={+ 200: LLMSkillManifestSerializer(many=True),+ 304: OpenApiResponse(+ description="Not modified. The client sent an If-None-Match that matches the current manifests."+ ),+ },+ )+ @action(methods=["GET"], detail=False, url_path="manifests", required_scopes=["llm_skill:read"])+ @llma_track_latency("llma_skills_manifests")+ @monitor(feature=None, endpoint="llma_skills_manifests", method="GET")+ def manifests(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponseBase:+ """The resource manifest of the latest version of each skill, paged and filtered like the list."""+ version = team_skills_version(self.team)+ return self._conditional_list_response(request, self._manifests_response(request), version)++ def _manifests_response(self, request: Request) -> Response:+ params = self._validated_query(LLMSkillManifestListQuerySerializer, request)+ queryset = self.filter_queryset(+ list_queryset(+ team=self.team,+ user_access_control=self.user_access_control,+ params=params,+ query_params=request.query_params,+ )+ ).defer("body")+ if "exclude_category" in params:+ queryset = queryset.exclude(category=params["exclude_category"])++ page = self.paginate_queryset(queryset)+ skills = [self._apply_trial_skill(request, skill) for skill in (queryset if page is None else page)]+ data = LLMSkillManifestSerializer(instance=build_skill_manifests(skills), many=True).data+ if page is not None:+ return self.get_paginated_response(data)+ return Response({"count": len(data), "results": data})++ def _conditional_list_response(self, request: Request, list_response: Response, version: str) -> HttpResponseBase:validators = self._list_validators(request, list_response, version)# Validate and apply access rules before a conditional response can reuse a cached body.response = get_conditional_response(request._request, etag=validators.etag) or list_responsediff --git a/products/skills/backend/api/test/test_skills.py b/products/skills/backend/api/test/test_skills.pyindex f226c4bc75e0..b0836f27a7c7 100644--- a/products/skills/backend/api/test/test_skills.py+++ b/products/skills/backend/api/test/test_skills.py@@ -1,5 +1,6 @@import uuidimport hashlib+import contextlibfrom datetime import timedeltafrom posthog.test.base import APIBaseTest@@ -1122,6 +1123,8 @@ class TestLLMSkillAPI(APIBaseTest):[("missing_skill", "name/nonexistent/skill-md"),("missing_version", "name/rendered/skill-md?version=9"),+ ("manifest_missing_skill", "name/nonexistent/manifest"),+ ("manifest_missing_version", "name/rendered/manifest?version=9"),])def test_skill_md_not_found(self, _label, path):@@ -1131,6 +1134,145 @@ class TestLLMSkillAPI(APIBaseTest):assert response.status_code == status.HTTP_404_NOT_FOUND+ # --- Resource manifests ---++ def test_manifest_digests_match_the_served_bytes(self):+ skill = self.create_skill(+ name="served",+ body="# Guía ✅\r\nDo the thing.",+ allowed_tools=["Read"],+ metadata={"author": "posthog", "nested": {"z": "1", "a": "2"}},+ )+ LLMSkillFile.objects.create(skill=skill, path="scripts/run.bat", content="echo hi\r\necho bye\r\n")+ LLMSkillFile.objects.create(+ skill=skill, path="references/guía.md", content="# Guía ✅\n", content_type="text/markdown"+ )++ with CaptureQueriesContext(connection) as captured_queries:+ response = self.client.get(self._url("name/served/manifest"))++ assert response.status_code == status.HTTP_200_OK+ manifest = response.json()+ skill_md = self.client.get(self._url("name/served/skill-md")).json()+ served = {"SKILL.md": skill_md["content"]}+ for path in ("references/guía.md", "scripts/run.bat"):+ served[path] = self.client.get(self._url(f"name/served/files/{path}")).json()["content"]+ assert [resource["path"] for resource in manifest["resources"]] == list(served)+ for resource in manifest["resources"]:+ content = served[resource["path"]].encode("utf-8")+ assert resource["sha256"] == hashlib.sha256(content).hexdigest(), resource["path"]+ assert resource["size"] == len(content), resource["path"]+ assert manifest["frontmatter"] == skill_md["frontmatter"]+ assert manifest["version"] == 1+ assert manifest["file_count"] == 3+ assert manifest["total_size"] == sum(len(content.encode("utf-8")) for content in served.values())+ assert (manifest["servable"], manifest["unservable_reasons"]) == (True, [])+ loaded_content = [+ query["sql"]+ for query in captured_queries.captured_queries+ if '"llm_analytics_llmskill"."body"' in query["sql"]+ or '"llm_analytics_llmskillfile"."content"' in query["sql"]+ ]+ assert loaded_content == []++ listed = self.client.get(self._url("manifests")).json()["results"]+ assert listed == [manifest]++ def test_manifest_pins_to_a_requested_version(self):+ first = self.create_skill(name="pinned", body="# v1", version=1, is_latest=False)+ self.create_skill(name="pinned", body="# v2", version=2)++ data = self.client.get(self._url("name/pinned/manifest?version=1")).json()++ assert data["version"] == 1+ assert data["frontmatter"]["metadata"]["version"] == "1"+ assert data["resources"][0]["sha256"] == first.skill_md_sha256++ @parameterized.expand(+ [+ ("too_many_files", "MCP_MAX_SKILL_FILES", "file_count", -1, {}, ["too_many_files"]),+ ("files_at_limit", "MCP_MAX_SKILL_FILES", "file_count", 0, {}, []),+ ("too_large", "MCP_MAX_SKILL_BYTES", "total_size", -1, {}, ["too_large"]),+ ("bytes_at_limit", "MCP_MAX_SKILL_BYTES", "total_size", 0, {}, []),+ ("digest_missing", None, None, 0, {"content_sha256": None, "content_size": None}, ["digest_missing"]),+ # Bypasses the serializer validation so the row looks like one that predates it.+ ("spec_problems", None, None, 0, {"path": "references\\guide.md"}, ["spec_problems"]),+ ]+ )+ def test_manifest_reports_whether_a_skill_is_servable(+ self, _label, limit_name, measured_field, limit_delta, file_update, expected_reasons+ ):+ skill = self.create_skill(name="limited")+ LLMSkillFile.objects.create(skill=skill, path="references/guide.md", content="# Guide")+ LLMSkillFile.objects.filter(skill=skill).update(**file_update)+ limit_patch: contextlib.AbstractContextManager = contextlib.nullcontext()+ if limit_name:+ measured = self.client.get(self._url("name/limited/manifest")).json()[measured_field]+ limit_patch = patch(f"products.skills.backend.api.skill_manifest.{limit_name}", measured + limit_delta)++ with limit_patch:+ response = self.client.get(self._url("name/limited/manifest"))++ assert response.status_code == status.HTTP_200_OK+ data = response.json()+ assert (data["servable"], data["unservable_reasons"]) == (not expected_reasons, expected_reasons)++ def test_manifests_query_count_does_not_grow_with_the_page(self):+ def add_skills(names: list[str], file_count: int) -> None:+ for name in names:+ skill = self.create_skill(name=name)+ for index in range(file_count):+ LLMSkillFile.objects.create(skill=skill, path=f"references/{index}.md", content="x")++ add_skills(["skill-a"], file_count=1)+ # The first request warms per-request caches, so it would count queries the page does not cost.+ self.client.get(self._url("manifests"))+ with CaptureQueriesContext(connection) as small_page:+ self.client.get(self._url("manifests"))+ add_skills(["skill-b", "skill-c", "skill-d"], file_count=3)+ with CaptureQueriesContext(connection) as large_page:+ response = self.client.get(self._url("manifests"))++ assert response.status_code == status.HTTP_200_OK+ assert sorted(entry["file_count"] for entry in response.json()["results"]) == [2, 4, 4, 4]+ assert len(large_page.captured_queries) == len(small_page.captured_queries)+ loaded_content = [+ query["sql"]+ for query in large_page.captured_queries+ if '"llm_analytics_llmskill"."body"' in query["sql"]+ or '"llm_analytics_llmskillfile"."content"' in query["sql"]+ ]+ assert loaded_content == []++ @parameterized.expand(+ [+ ("exclude_category", lambda self: "?exclude_category=scout", ["ordinary-skill", "theirs"]),+ ("owner_id", lambda self: f"?owner_id={self.user.id}", ["ordinary-skill", "signals-scout-errors"]),+ ]+ )+ def test_manifests_filter_like_the_list(self, _label, query_suffix, expected_names):+ self.create_skill(name="ordinary-skill")+ self.create_skill(name="signals-scout-errors", category="scout")+ self.create_skill(name="theirs", created_by=self._create_user("[email protected]"))++ response = self.client.get(self._url("manifests") + query_suffix(self))++ assert response.status_code == status.HTTP_200_OK+ assert sorted(entry["name"] for entry in response.json()["results"]) == expected_names++ def test_manifests_answer_304_until_a_publish(self):+ self.create_skill(name="skill-a")+ first = self.client.get(self._url("manifests"))++ unchanged = self.client.get(self._url("manifests"), HTTP_IF_NONE_MATCH=first["ETag"])+ publish_skill_version(self.team, user=self.user, skill_name="skill-a", body="# Changed", base_version=1)+ changed = self.client.get(self._url("manifests"), HTTP_IF_NONE_MATCH=first["ETag"])++ assert unchanged.status_code == status.HTTP_304_NOT_MODIFIED+ assert changed.status_code == status.HTTP_200_OK+ assert changed["ETag"] != first["ETag"]+ assert [entry["version"] for entry in changed.json()["results"]] == [2]+# --- Publish new version ---def test_publish_new_version(self):@@ -2852,7 +2994,11 @@ class TestSkillAccessControlRBAC(APIBaseTest):assert response.status_code == status.HTTP_200_OK, response.json()@parameterized.expand(- [(access, endpoint) for access in ("none", "viewer") for endpoint in ("list", "body", "file", "id")]+ [+ (access, endpoint)+ for access in ("none", "viewer")+ for endpoint in ("list", "manifests", "body", "file", "manifest", "id")+ ])def test_list_and_reads_respect_individual_skill_grants(self, resource_access: str, endpoint: str) -> None:self._grant_llm_skill_access(resource_access)@@ -2874,8 +3020,9 @@ class TestSkillAccessControlRBAC(APIBaseTest):)LLMSkillFile.objects.create(skill=skill, path="reference.md", content=f"Reference for {skill.name}")- if endpoint == "list":- response = self.client.get(self._url(), {"limit": "1", "order_by": "name"})+ if endpoint in ("list", "manifests"):+ url = self._url() if endpoint == "list" else self._url("manifests")+ response = self.client.get(url, {"limit": "1", "order_by": "name"})assert response.status_code == status.HTTP_200_OKassert response.json()["count"] == 1assert [skill["name"] for skill in response.json()["results"]] == [self.skill.name]@@ -2886,9 +3033,7 @@ class TestSkillAccessControlRBAC(APIBaseTest):resource_id=str(restricted.id),organization_member=membership,).update(access_level=access)- response = self.client.get(- self._url(), {"limit": "1", "order_by": "name"}, HTTP_IF_NONE_MATCH=response["ETag"]- )+ response = self.client.get(url, {"limit": "1", "order_by": "name"}, HTTP_IF_NONE_MATCH=response["ETag"])assert response.status_code == status.HTTP_200_OKassert response.json()["count"] == expected_countreturn@@ -2896,7 +3041,7 @@ class TestSkillAccessControlRBAC(APIBaseTest):allowed_status = status.HTTP_302_FOUND if endpoint == "id" else status.HTTP_200_OKfor skill, expected_status in [(self.skill, allowed_status), (restricted, status.HTTP_403_FORBIDDEN)]:name = str(skill.id) if endpoint == "id" else skill.name- suffix = "/files/reference.md" if endpoint == "file" else ""+ suffix = {"file": "/files/reference.md", "manifest": "/manifest"}.get(endpoint, "")version_params: list[dict[str, int]] = [{}, {"version": 1}]for params in version_params:response = self.client.get(self._url(f"name/{name}{suffix}"), params)@@ -3000,7 +3145,9 @@ class TestScoutTrialSkillAPI(APIBaseTest):f"/api/projects/{self.team.id}/llm_skills/resolve/name/{self.source.name}?{query}")exported = self.client.get(self._url(f"/export?{query}"))+ manifest = self.client.get(self._url(f"/manifest?{query}"))listed = self.client.get(f"/api/projects/{self.team.id}/llm_skills/")+ listed_manifests = self.client.get(f"/api/projects/{self.team.id}/llm_skills/manifests/")other = self.client.get(f"/api/environments/{self.team.id}/llm_skills/name/another-skill?launch_id={uuid.uuid4()}")@@ -3021,6 +3168,12 @@ class TestScoutTrialSkillAPI(APIBaseTest):assert listed.status_code == status.HTTP_200_OKlisted_skill = next(skill for skill in listed.json()["results"] if skill["name"] == self.source.name)assert listed_skill["version"] == 1+ rendered_sha256 = hashlib.sha256(rendered.encode("utf-8")).hexdigest()+ listed_manifest = next(m for m in listed_manifests.json()["results"] if m["name"] == self.source.name)+ for served in (manifest.json(), listed_manifest):+ assert served["version"] == 1+ skill_md = served["resources"][0]+ assert (skill_md["path"], skill_md["sha256"]) == ("SKILL.md", rendered_sha256)assert other.status_code == status.HTTP_200_OKassert other.json()["body"] == "other instructions"self.source.refresh_from_db()diff --git a/products/skills/backend/marketplace/README.md b/products/skills/backend/marketplace/README.mdindex b7b306f275f6..140d6fb76d5d 100644--- a/products/skills/backend/marketplace/README.md+++ b/products/skills/backend/marketplace/README.md@@ -40,6 +40,10 @@ unit-testable against the real `git` binary without booting the appBehind the `skills-store-in-sandbox` flag (off → 404, flag service unavailable → 503).`llm_skill:read`, which the sandbox OAuth token already carries. Throttled per user, so one callercannot 429 the rest of the project. Consumer-facing contract: `docs/internal/skills/skill-bundle-api.md`.+- **Resource manifests** — `GET /api/projects/:team/llm_skills/name/:name/manifest/?version=N` and the paged+ `GET /api/projects/:team/llm_skills/manifests/` return every file of a skill (`SKILL.md` first) with the stored+ SHA-256 and byte size, plus a `servable` flag against the MCP Skills extension limits, for the MCP server's+ `skills/get` and `skills/list`. `llm_skill:read`. Contract: `docs/internal/skills/skill-md-api.md`.- **Sandbox run state** — `select_skill_stubs` in `adapters.py` is the same stub walk without the zip.The tasks worker calls it when it builds a run's processing context and writes the entries into`TaskRun.state["store_skills"]` (`products/tasks/backend/logic/services/store_skills.py`); the sandboxdiff --git a/products/skills/backend/marketplace/packaging.py b/products/skills/backend/marketplace/packaging.pyindex ee79fb9a2a6f..e24632a5794d 100644--- a/products/skills/backend/marketplace/packaging.py+++ b/products/skills/backend/marketplace/packaging.py@@ -140,6 +140,13 @@ def utf8_digest(content: str) -> tuple[str, int]:return hashlib.sha256(encoded).hexdigest(), len(encoded)+# The MCP Skills extension says a server SHOULD NOT serve a skill with more files than this (SKILL.md+# included) or more bytes than this (the sum of every resource size). The store allows more, so a+# manifest reports such a skill as unservable rather than the store rejecting it on write.+MCP_MAX_SKILL_FILES = 512+MCP_MAX_SKILL_BYTES = 16 * 1024 * 1024++@dataclass(frozen=True)class SkillStub:"""The discovery half of a skill: enough for a harness to list and invoke it by name."""diff --git a/products/skills/backend/models/skills.py b/products/skills/backend/models/skills.pyindex 208c4dae23b1..e5a6ae8110a9 100644--- a/products/skills/backend/models/skills.py+++ b/products/skills/backend/models/skills.py@@ -107,17 +107,20 @@ class LLMSkill(UUIDModel):objects = SkillDigestManager()- def to_export(self, files: "list[LLMSkillFile] | None" = None) -> SkillExport:+ def to_export(self, files: "list[LLMSkillFile] | None" = None, *, include_body: bool = True) -> SkillExport:"""Map this row onto the Django-free spec dataclass. The one storage -> spec mapping.The digest below and the exported artifact must describe the same bytes, so they cannoteach carry their own copy of this mapping — a spec field added to one and not the otherwould make every host reject the file it downloads.++ ``include_body=False`` leaves the body empty without reading it, for a caller that only+ needs the frontmatter and loaded the row with the body deferred."""return SkillExport(name=self.name,description=self.description,- body=self.body,+ body=self.body if include_body else "",version=self.version,license=self.license or "",compatibility=self.compatibility or "",diff --git a/products/skills/frontend/generated/api.schemas.ts b/products/skills/frontend/generated/api.schemas.tsindex d215dee42271..e5090077f9ab 100644--- a/products/skills/frontend/generated/api.schemas.ts+++ b/products/skills/frontend/generated/api.schemas.ts@@ -596,6 +596,81 @@ export interface LLMSkillImportApi {file: string}+export interface LLMSkillManifestResourceApi {+ /** Path of the file relative to the skill directory. SKILL.md for the rendered skill file. */+ path: string+ /**+ * Bare hex SHA-256 of the exact bytes served for this file, without a 'sha256:' prefix. Null on rows written before digests were stamped.+ * @nullable+ */+ sha256: string | null+ /**+ * Byte length of the exact bytes served for this file, encoded as UTF-8. Null on rows written before digests were stamped.+ * @nullable+ */+ size: number | null+ /** MIME type of the file, e.g. text/markdown. */+ content_type: string+}++/**+ * * `too_many_files` - Too many files+ * * `too_large` - Too large+ * * `digest_missing` - Digest missing+ * * `spec_problems` - Spec problems+ */+export type SkillUnservableReasonEnumApi =+ (typeof SkillUnservableReasonEnumApi)[keyof typeof SkillUnservableReasonEnumApi]++export const SkillUnservableReasonEnumApi = {+ TooManyFiles: 'too_many_files',+ TooLarge: 'too_large',+ DigestMissing: 'digest_missing',+ SpecProblems: 'spec_problems',+} as const++export type LLMSkillManifestApiFrontmatterMetadata = { [key: string]: string }++/**+ * The frontmatter of the served SKILL.md as a JSON object, equal to the frontmatter field of the skill-md endpoint for the same version.+ */+export type LLMSkillManifestApiFrontmatter = {+ name: string+ description: string+ license?: string+ compatibility?: string+ metadata: LLMSkillManifestApiFrontmatterMetadata+ 'allowed-tools'?: string+}++export interface LLMSkillManifestApi {+ /** Name of the skill, which is also its directory name. */+ name: string+ /** Version of the skill that this manifest describes. */+ version: number+ /** The frontmatter of the served SKILL.md as a JSON object, equal to the frontmatter field of the skill-md endpoint for the same version. */+ frontmatter: LLMSkillManifestApiFrontmatter+ /** Every file of the skill exactly once: SKILL.md first, then the bundled files sorted by path. */+ resources: LLMSkillManifestResourceApi[]+ /** Number of entries in resources, SKILL.md included. */+ file_count: number+ /** Sum of every resource size in bytes. A resource with a null size counts as zero. */+ total_size: number+ /** Whether an MCP server may serve this skill. False when unservable_reasons is not empty. */+ servable: boolean+ /** Why the skill must not be served, one code per reason. too_many_files: more than 512 files. too_large: more than 16777216 bytes in total. digest_missing: a stored digest or size is null. spec_problems: the skill fails the Agent Skills spec check, see spec_problems on the skill. */+ unservable_reasons: SkillUnservableReasonEnumApi[]+}++export interface PaginatedLLMSkillManifestListApi {+ count: number+ /** @nullable */+ next?: string | null+ /** @nullable */+ previous?: string | null+ results: LLMSkillManifestApi[]+}+/*** * `absent` - absent* * `exists` - exists@@ -1064,6 +1139,37 @@ export const LlmSkillsBundleRetrieveContent = {Full: 'full',} as const+export type LlmSkillsManifestsListParams = {+ /**+ * Filter skills to this exact category. Pass "scout" for Signals scouts, or an empty string to return only uncategorized skills. Omit the parameter entirely to return skills of every category.+ */+ category?: string+ /**+ * Filter skills by the ID of the user who created them.+ */+ created_by_id?: number+ /**+ * Leave out skills in this exact category, e.g. "scout" to skip Signals scouts. An empty string leaves out uncategorized skills.+ */+ exclude_category?: string+ /**+ * Number of results to return per page.+ */+ limit?: number+ /**+ * The initial index from which to return the results.+ */+ offset?: number+ /**+ * Filter skills by the ID of a user who owns them. Ownership is keyed on the logical skill, so this is stable across versions — unlike created_by_id, which tracks whoever published the latest version.+ */+ owner_id?: number+ /**+ * Optional substring filter applied to skill names and descriptions.+ */+ search?: string+}+export type LlmSkillsNameRetrieveParams = {/*** Maximum number of characters of the body to return starting at body_offset. Omit to return the whole body from the offset onwards. When the slice stops before the end, body_next_offset is the offset to request next.@@ -1106,6 +1212,14 @@ export type LlmSkillsNameFilesDestroyParams = {base_version?: number}+export type LlmSkillsNameManifestRetrieveParams = {+ /**+ * Specific skill version to fetch. If omitted, the latest version is returned.+ * @minimum 1+ */+ version?: number+}+export type LlmSkillsNameSkillMdRetrieveParams = {/*** Specific skill version to fetch. If omitted, the latest version is returned.diff --git a/products/skills/frontend/generated/api.ts b/products/skills/frontend/generated/api.tsindex 71ba53d0d1f7..36e1f1273450 100644--- a/products/skills/frontend/generated/api.ts+++ b/products/skills/frontend/generated/api.ts@@ -23,6 +23,7 @@ import type {LLMSkillFileCreateApi,LLMSkillFileRenameApi,LLMSkillImportApi,+ LLMSkillManifestApi,LLMSkillMarkdownApi,LLMSkillMarketplaceCommandApi,LLMSkillMarketplaceIssueApi,@@ -32,15 +33,18 @@ import type {LLMSkillSearchResponseApi,LlmSkillsBundleRetrieveParams,LlmSkillsListParams,+ LlmSkillsManifestsListParams,LlmSkillsNameExportRetrieveParams,LlmSkillsNameFilesDestroyParams,LlmSkillsNameFilesRetrieveParams,+ LlmSkillsNameManifestRetrieveParams,LlmSkillsNameRetrieveParams,LlmSkillsNameSkillMdRetrieveParams,LlmSkillsResolveNameRetrieveParams,LlmSkillsSearchRetrieveParams,PaginatedCommunitySkillListListApi,PaginatedLLMSkillListListApi,+ PaginatedLLMSkillManifestListApi,PatchedLLMSkillPublishApi,} from './api.schemas'@@ -253,6 +257,36 @@ export const llmSkillsImportCreate = async (})}+export const getLlmSkillsManifestsListUrl = (projectId: string, params?: LlmSkillsManifestsListParams) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/llm_skills/manifests/?${stringifiedParams}`+ : `/api/projects/${projectId}/llm_skills/manifests/`+}++/**+ * The resource manifest of the latest version of each skill, paged and filtered like the list.+ */+export const llmSkillsManifestsList = async (+ projectId: string,+ params?: LlmSkillsManifestsListParams,+ options?: RequestInit+): Promise<PaginatedLLMSkillManifestListApi> => {+ return apiMutator<PaginatedLLMSkillManifestListApi>(getLlmSkillsManifestsListUrl(projectId, params), {+ ...options,+ method: 'GET',+ })+}+export const getLlmSkillsMarketplaceInstallCommandRetrieveUrl = (projectId: string) => {return `/api/projects/${projectId}/llm_skills/marketplace/install-command/`}@@ -514,6 +548,43 @@ export const llmSkillsNameFilesDestroy = async (})}+export const getLlmSkillsNameManifestRetrieveUrl = (+ projectId: string,+ skillName: string,+ params?: LlmSkillsNameManifestRetrieveParams+) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/llm_skills/name/${skillName}/manifest/?${stringifiedParams}`+ : `/api/projects/${projectId}/llm_skills/name/${skillName}/manifest/`+}++/**+ * Every file of one skill with the digest and size of the bytes the store serves for it.+ *+ * Answers an unservable skill with 200 too, so a caller can log why it skips the skill.+ */+export const llmSkillsNameManifestRetrieve = async (+ projectId: string,+ skillName: string,+ params?: LlmSkillsNameManifestRetrieveParams,+ options?: RequestInit+): Promise<LLMSkillManifestApi> => {+ return apiMutator<LLMSkillManifestApi>(getLlmSkillsNameManifestRetrieveUrl(projectId, skillName, params), {+ ...options,+ method: 'GET',+ })+}+export const getLlmSkillsNamePublishCommunityCreateUrl = (projectId: string, skillName: string) => {return `/api/projects/${projectId}/llm_skills/name/${skillName}/publish-community/`}diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 179bc94d6c32..81db34514b1c 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -65896,6 +65896,72 @@ export namespace Schemas {readonly first_version_created_at: string;}+ export type LLMSkillManifestFrontmatterMetadata = {[key: string]: string};++ /**+ * The frontmatter of the served SKILL.md as a JSON object, equal to the frontmatter field of the skill-md endpoint for the same version.+ */+ export type LLMSkillManifestFrontmatter = {+ name: string;+ description: string;+ license?: string;+ compatibility?: string;+ metadata: LLMSkillManifestFrontmatterMetadata;+ 'allowed-tools'?: string;+ };++ export interface LLMSkillManifestResource {+ /** Path of the file relative to the skill directory. SKILL.md for the rendered skill file. */+ path: string;+ /**+ * Bare hex SHA-256 of the exact bytes served for this file, without a 'sha256:' prefix. Null on rows written before digests were stamped.+ * @nullable+ */+ sha256: string | null;+ /**+ * Byte length of the exact bytes served for this file, encoded as UTF-8. Null on rows written before digests were stamped.+ * @nullable+ */+ size: number | null;+ /** MIME type of the file, e.g. text/markdown. */+ content_type: string;+ }++ /**+ * * `too_many_files` - Too many files+ * * `too_large` - Too large+ * * `digest_missing` - Digest missing+ * * `spec_problems` - Spec problems+ */+ export type SkillUnservableReasonEnum = typeof SkillUnservableReasonEnum[keyof typeof SkillUnservableReasonEnum];+++ export const SkillUnservableReasonEnum = {+ TooManyFiles: 'too_many_files',+ TooLarge: 'too_large',+ DigestMissing: 'digest_missing',+ SpecProblems: 'spec_problems',+ } as const;++ export interface LLMSkillManifest {+ /** Name of the skill, which is also its directory name. */+ name: string;+ /** Version of the skill that this manifest describes. */+ version: number;+ /** The frontmatter of the served SKILL.md as a JSON object, equal to the frontmatter field of the skill-md endpoint for the same version. */+ frontmatter: LLMSkillManifestFrontmatter;+ /** Every file of the skill exactly once: SKILL.md first, then the bundled files sorted by path. */+ resources: LLMSkillManifestResource[];+ /** Number of entries in resources, SKILL.md included. */+ file_count: number;+ /** Sum of every resource size in bytes. A resource with a null size counts as zero. */+ total_size: number;+ /** Whether an MCP server may serve this skill. False when unservable_reasons is not empty. */+ servable: boolean;+ /** Why the skill must not be served, one code per reason. too_many_files: more than 512 files. too_large: more than 16777216 bytes in total. digest_missing: a stored digest or size is null. spec_problems: the skill fails the Agent Skills spec check, see spec_problems on the skill. */+ unservable_reasons: SkillUnservableReasonEnum[];+ }+export type LLMSkillMarkdownFrontmatterMetadata = {[key: string]: string};/**@@ -76118,6 +76184,15 @@ export namespace Schemas {results: LLMSkillList[];}+ export interface PaginatedLLMSkillManifestList {+ count: number;+ /** @nullable */+ next?: string | null;+ /** @nullable */+ previous?: string | null;+ results: LLMSkillManifest[];+ }+export interface PaginatedLegalDocumentDTOList {count: number;/** @nullable */@@ -134960,6 +135035,37 @@ export namespace Schemas {Full: 'full',} as const;+ export type LlmSkillsManifestsListParams = {+ /**+ * Filter skills to this exact category. Pass "scout" for Signals scouts, or an empty string to return only uncategorized skills. Omit the parameter entirely to return skills of every category.+ */+ category?: string;+ /**+ * Filter skills by the ID of the user who created them.+ */+ created_by_id?: number;+ /**+ * Leave out skills in this exact category, e.g. "scout" to skip Signals scouts. An empty string leaves out uncategorized skills.+ */+ exclude_category?: string;+ /**+ * Number of results to return per page.+ */+ limit?: number;+ /**+ * The initial index from which to return the results.+ */+ offset?: number;+ /**+ * Filter skills by the ID of a user who owns them. Ownership is keyed on the logical skill, so this is stable across versions — unlike created_by_id, which tracks whoever published the latest version.+ */+ owner_id?: number;+ /**+ * Optional substring filter applied to skill names and descriptions.+ */+ search?: string;+ };+export type LlmSkillsNameRetrieveParams = {/*** Maximum number of characters of the body to return starting at body_offset. Omit to return the whole body from the offset onwards. When the slice stops before the end, body_next_offset is the offset to request next.@@ -135002,6 +135108,14 @@ export namespace Schemas {base_version?: number;};+ export type LlmSkillsNameManifestRetrieveParams = {+ /**+ * Specific skill version to fetch. If omitted, the latest version is returned.+ * @minimum 1+ */+ version?: number;+ };+export type LlmSkillsNameSkillMdRetrieveParams = {/*** Specific skill version to fetch. If omitted, the latest version is returned.