Skip to content

: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.

fix(skills): validate community catalog limits before publishing (#130601)

Jake Ruth0b120ed4edf4
diff --git a/docs/internal/skills/community-skills-api.md b/docs/internal/skills/community-skills-api.md
index a5eb4f05ae6e..db195ae4d0d7 100644
--- a/docs/internal/skills/community-skills-api.md
+++ b/docs/internal/skills/community-skills-api.md
@@ -160,6 +160,10 @@ After a conflict, retrieve the skill again and require new consent before anothe
against the publisher's PostHog account, so the PR body presents it as a handle the publisher gave.
- Bundled files are text only. `CommunitySkillFile.content` is a `TextField` and the renderer takes
`str`, so a skill referencing an image or other binary asset cannot round-trip through the catalog.
+- Community publishing also checks the smaller limits in `PostHog/community-skills/scripts/build_registry.py`: at most 256 KiB (262,144 bytes) per bundled file and 1 MiB (1,048,576 bytes) for the body plus bundled files.
+ The total counts the UTF-8 body after normalizing line endings and trimming surrounding whitespace, plus each bundled file's UTF-8 bytes. YAML frontmatter is excluded, and the per-file limit does not apply to the body.
+ The store's existing body and file-count limits still apply. The separate 5,000,000-byte limit on the encoded GitHub tree request includes frontmatter, file paths, and JSON escaping.
+ An oversized skill returns `400` before acquiring a GitHub publisher or writing a branch.
- Template skills publish their normalized `metadata.variables` schema (and no other store metadata).
Publishing checks that the template installs with only its defaults: every `{{ variable }}` in
`SKILL.md` or a bundled file is declared, and the defaults and rendered output fit the install
diff --git a/products/skills/backend/api/community_publish_services.py b/products/skills/backend/api/community_publish_services.py
index 44e2f5c2736a..825f18efbc09 100644
--- a/products/skills/backend/api/community_publish_services.py
+++ b/products/skills/backend/api/community_publish_services.py
@@ -51,6 +51,9 @@ logger = structlog.get_logger(__name__)
_EGRESS_SOURCE = "community_skills"
MAX_SLUG_LENGTH = 64
+# Keep these aligned with PostHog/community-skills scripts/build_registry.py.
+MAX_COMMUNITY_FILE_BYTES = 256 * 1024
+MAX_COMMUNITY_SKILL_BYTES = 1024 * 1024
# GitHub caps one create-tree request at 7 MB, and commit_files_to_branch inlines every file's
# content in that single request, so a skill above the cap can only ever fail with a 502. Measured
# against the escaped form the request actually carries, and held under the cap for the frontmatter,
@@ -425,11 +428,11 @@ def _encoded_payload_bytes(content: str) -> int:
def _validate_entry_caps(*, body: str, files: list[dict[str, str]]) -> None:
- """Hold a publish to ingest's own per-entry caps, which it measures on the stored bytes.
+ """Validate ingest limits and the catalog builder's smaller content limits.
- These are `community_skill_sync._validate_entry_within_caps`, where breaching one drops the whole
- entry: the pull request merges and the skill never appears in the catalog. The file count is
- checked here rather than after rendering so an absurd manifest never gets rendered at all.
+ Ingest checks the store caps; community-skills scripts/build_registry.py also checks bundled
+ files and total embedded content. Check both before creating a public pull request that cannot
+ reach the catalog, and check file count before rendering the manifest.
"""
if len(body.encode("utf-8")) > MAX_SKILL_BODY_BYTES:
raise CommunitySkillPublishValidationError(
@@ -437,11 +440,26 @@ def _validate_entry_caps(*, body: str, files: list[dict[str, str]]) -> None:
)
if len(files) > MAX_SKILL_FILE_COUNT:
raise CommunitySkillPublishValidationError(f"A skill can publish at most {MAX_SKILL_FILE_COUNT} files.")
+ # The catalog reads SKILL.md with universal newlines, then strips its body and excludes frontmatter.
+ total_bytes = len(body.replace("\r\n", "\n").replace("\r", "\n").strip().encode("utf-8"))
for file in files:
- if len(file["content"].encode("utf-8")) > MAX_SKILL_FILE_BYTES:
+ file_bytes = len(file["content"].encode("utf-8"))
+ if file_bytes > MAX_SKILL_FILE_BYTES:
raise CommunitySkillPublishValidationError(
f"'{file['path']}' must be under {MAX_SKILL_FILE_BYTES // 1_000_000} MB."
)
+ if file_bytes > MAX_COMMUNITY_FILE_BYTES:
+ raise CommunitySkillPublishValidationError(
+ f"'{file['path']}' exceeds the community catalog's {MAX_COMMUNITY_FILE_BYTES // 1024} KiB file limit. "
+ "Reduce the file size before publishing."
+ )
+ total_bytes += file_bytes
+ if total_bytes > MAX_COMMUNITY_SKILL_BYTES:
+ raise CommunitySkillPublishValidationError(
+ f"The skill body and bundled files exceed the community catalog's "
+ f"{MAX_COMMUNITY_SKILL_BYTES // (1024 * 1024)} MiB total limit. "
+ "Reduce their combined size before publishing."
+ )
def _validate_publishable_tree_size(rendered: list[RenderedFile]) -> None:
diff --git a/products/skills/backend/api/test/test_community_publish_services.py b/products/skills/backend/api/test/test_community_publish_services.py
index d3d5714e7632..eb191a24ed8d 100644
--- a/products/skills/backend/api/test/test_community_publish_services.py
+++ b/products/skills/backend/api/test/test_community_publish_services.py
@@ -339,6 +339,61 @@ class TestRenderCommunitySkillFiles:
class TestPublishableSize:
+ @pytest.mark.parametrize("content", ["x" * (256 * 1024 + 1), "é" * (128 * 1024) + "x", "\r\n" * (128 * 1024 + 1)])
+ def test_rejects_bundled_files_over_the_community_catalog_limit(self, content: str) -> None:
+ with pytest.raises(CommunitySkillPublishValidationError, match="256 KiB"):
+ render_community_skill_files(
+ slug="make-pr",
+ name="n",
+ description="d",
+ body="b",
+ files=[{"path": "references/guide.md", "content": content}],
+ )
+
+ @pytest.mark.parametrize(
+ "body",
+ [
+ "x" * (256 * 1024 + 1),
+ "é" * (128 * 1024) + "x",
+ "x\r\n" * (128 * 1024 - 1) + "xxx",
+ "x\r" * (128 * 1024 - 1) + "xxx",
+ ],
+ ids=["ascii", "utf8", "crlf", "cr"],
+ )
+ def test_rejects_body_and_files_over_the_community_catalog_total(self, body: str) -> None:
+ with pytest.raises(CommunitySkillPublishValidationError, match="1 MiB"):
+ render_community_skill_files(
+ slug="make-pr",
+ name="n",
+ description="d",
+ body=body,
+ files=[{"path": f"references/{index}.md", "content": "x" * (256 * 1024)} for index in range(3)],
+ )
+
+ @pytest.mark.parametrize(
+ "body,content,file_count",
+ [
+ ("b", "x" * (256 * 1024), 1),
+ ("b", "é" * (128 * 1024), 1),
+ ("x" * (300 * 1024), "", 0),
+ ("x" * (256 * 1024), "x" * (256 * 1024), 3),
+ (" \n" + "x" * (256 * 1024) + "\n ", "x" * (256 * 1024), 3),
+ ("x\r\n" * (128 * 1024 - 1) + "xx", "x" * (256 * 1024), 3),
+ ],
+ ids=["file-boundary", "utf8-file-boundary", "large-body", "total-boundary", "body-whitespace", "body-crlf"],
+ )
+ def test_renders_skills_within_community_catalog_limits(self, body: str, content: str, file_count: int) -> None:
+ rendered = render_community_skill_files(
+ slug="make-pr",
+ name="n",
+ description="d",
+ body=body,
+ files=[{"path": f"references/{index}.md", "content": content} for index in range(file_count)],
+ )
+
+ assert _parse(rendered[0].content)[1] == body.strip()
+ assert [file.content for file in rendered[1:]] == [content] * file_count
+
@parameterized.expand(
[
# Ingest's own per-entry caps: breaching one drops the whole entry, so the pull request
@@ -346,8 +401,6 @@ class TestPublishableSize:
("body over the catalog cap", "x" * (MAX_SKILL_BODY_BYTES + 1), 1, 10),
("more files than the catalog takes", "b", MAX_SKILL_FILE_COUNT + 1, 10),
("one file over the catalog cap", "b", 1, MAX_SKILL_FILE_BYTES + 1),
- # GitHub's cap on a single create-tree request, which inlines every file's content.
- ("files summing over the tree cap", "b", 6, MAX_SKILL_FILE_BYTES),
]
)
def test_rejects_a_skill_no_publish_could_survive(
@@ -370,33 +423,26 @@ class TestPublishableSize:
# measuring the fields the files came from instead of the files themselves leaves the
# difference between them unbounded.
files = [
- {"path": f"references/{index}.md", "content": "x" * MAX_SKILL_FILE_BYTES, "content_type": "text/markdown"}
+ {"path": f"references/{index}.md", "content": "\x01" * 200_000, "content_type": "text/markdown"}
for index in range(4)
]
- fields: dict[str, Any] = {"slug": "make-pr", "name": "n", "description": "d", "body": "x" * 990_000}
+ fields: dict[str, Any] = {"slug": "make-pr", "name": "n", "description": "d", "body": "b"}
render_community_skill_files(**fields, files=files)
- with pytest.raises(CommunitySkillPublishError):
+ with pytest.raises(CommunitySkillPublishValidationError, match="5 MB"):
render_community_skill_files(**fields, files=files, tags=["t" * MAX_TAG_LENGTH] * 4000)
def test_rejects_a_skill_whose_encoded_payload_blows_the_tree_cap(self) -> None:
- # 3 MB of newlines clears every raw-byte check, and doubles once escaped into the single JSON
- # body the tree write inlines it in. Counted raw, this publishes and then fails against
- # GitHub with a 502 the publisher can do nothing with.
- with pytest.raises(CommunitySkillPublishError):
+ with pytest.raises(CommunitySkillPublishValidationError, match="5 MB"):
render_community_skill_files(
slug="make-pr",
name="n",
description="d",
body="b",
files=[
- {
- "path": f"references/{index}.md",
- "content": "\n" * MAX_SKILL_FILE_BYTES,
- "content_type": "text/markdown",
- }
- for index in range(3)
+ {"path": f"references/{index}.md", "content": "\x01" * 250_000, "content_type": "text/markdown"}
+ for index in range(4)
],
)
@@ -545,7 +591,22 @@ class TestPublishSkillToCommunity:
files=[{"path": "references/playbook.md", "content": "hints", "content_type": "text/markdown"}],
)
- def test_a_skill_that_cannot_be_published_is_rejected_before_the_publisher_is_acquired(self) -> None:
+ @pytest.mark.parametrize(
+ "description,body,files",
+ [
+ ("", "body", []),
+ ("d", "body", [{"path": "references/guide.md", "content": "x" * (300 * 1024)}]),
+ (
+ "d",
+ "body",
+ [{"path": f"references/{index}.md", "content": "x" * (220 * 1024)} for index in range(5)],
+ ),
+ ],
+ ids=["missing-description", "catalog-file-limit", "catalog-total-limit"],
+ )
+ def test_a_skill_that_cannot_be_published_is_rejected_before_the_publisher_is_acquired(
+ self, description: str, body: str, files: list[dict[str, str]]
+ ) -> None:
# Acquiring the publisher talks to GitHub, so a skill that fails rendering used to come back
# as 502 or 503 whenever the App was down or unconfigured — advice to retry, for a publish
# that can only succeed once the publisher edits the skill.
@@ -555,7 +616,7 @@ class TestPublishSkillToCommunity:
):
with pytest.raises(CommunitySkillPublishValidationError):
publish_skill_to_community(
- slug="make-pr", publisher_id=TEAM_A, name="Make PR", description="", body="body"
+ slug="make-pr", publisher_id=TEAM_A, name="Make PR", description=description, body=body, files=files
)
def test_commits_every_file_in_one_commit(self) -> None: