: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
from dataclasses import asdict
from typing import Any
from django.db import transaction
from django.db.models import F, Value
from django.db.models.functions import Length, Replace
from drf_spectacular.utils import extend_schema_field, extend_schema_serializer
from rest_framework import serializers
from posthog.api.shared import UserBasicSerializer
from products.ai_observability.backend.markdown_outline import get_markdown_outline
from ..activity_logging import log_skill_activity
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_name
from .community_publish_services import (
DISPLAY_NAME_PATTERN,
MAX_DISPLAY_NAME_LENGTH,
MAX_GITHUB_HANDLE_LENGTH,
MAX_TAG_LENGTH,
OPTIONAL_GITHUB_HANDLE_PATTERN,
)
from .community_skill_serializers import CommunitySkillScoutConfigSerializer
from .skill_manifest import SkillUnservableReason
from .skill_services import (
MAX_SKILL_NAME_LENGTH,
RESERVED_SKILL_NAMES,
SKILL_NAME_PATTERN,
LLMSkillOwnerNotFoundError,
bundled_skill_name_error,
check_allowed_tool_name,
compute_spec_problems,
normalize_skill_file_path,
resolve_owner_users,
resolve_skill_metadata,
resolve_skill_owners,
seed_skill_owner,
set_skill_owners,
)
DEFAULT_VERSION_PAGE_SIZE = 50
# Body-paging metadata is meaningless without the body, so the list serializer drops it alongside body/files.
_LIST_EXCLUDED_FIELDS = ("body", "body_total_length", "body_next_offset", "files")
MAX_SKILL_BODY_BYTES = 1_000_000
MAX_SKILL_FILE_BYTES = 1_000_000
MAX_SKILL_FILE_COUNT = 200
# Ownership is a short routing list, not an ACL — cap it so a create/update can't resolve membership,
# clear the owner set, and insert an owner row per entry for an oversized input before being rejected.
MAX_SKILL_OWNERS = 25
# skill-get returns the whole body when the caller doesn't page, but a large body is
# truncated by the MCP transport before it reaches an agent — and an un-paged response
# reported body_next_offset as null, so the agent had no valid offset to continue from and
# would treat a cut-off body as complete. get_by_name caps the first page at this length so
# body_next_offset is always a real continuation offset the caller can page from until it is
# null, never a guess. Sized to sit under observed transport truncation with room for the
# response envelope (outline, file manifest, metadata).
DEFAULT_BODY_PAGE_LENGTH = 8000
# Tools that opt a scout skill into the report channel. Local copy of
# products/signals/backend/scout_harness/skill_loader.REPORT_CHANNEL_TOOLS — skills must not
# import signals internals, and drift fails closed: a report tool unknown here keeps owners
# hidden from scout callers rather than exposing them.
SCOUT_REPORT_CHANNEL_TOOLS = frozenset({"emit_report", "edit_report"})
def validate_skill_name_value(value: str) -> str:
if value.lower() in RESERVED_SKILL_NAMES:
raise serializers.ValidationError(
f"'{value}' is a reserved name and cannot be used.",
code="reserved_name",
)
if len(value) > MAX_SKILL_NAME_LENGTH:
raise serializers.ValidationError(
f"Skill name must be {MAX_SKILL_NAME_LENGTH} characters or fewer.",
code="max_length",
)
if not SKILL_NAME_PATTERN.fullmatch(value):
raise serializers.ValidationError(
"Only lowercase letters, numbers, and hyphens are allowed. "
"Must not start or end with a hyphen or contain consecutive hyphens.",
code="invalid_name",
)
if "--" in value:
raise serializers.ValidationError(
"Consecutive hyphens are not allowed.",
code="invalid_name",
)
return value
def validate_new_skill_name_value(value: str) -> str:
"""Validate a name a team is claiming for a skill: create, rename, duplicate, install, import.
Adds the bundled-name rule to `validate_skill_name_value`, which stays the looser contract for
a name that points at a skill the project already holds (see `bundled_skill_name_error`).
"""
value = validate_skill_name_value(value)
if error := bundled_skill_name_error(value):
raise serializers.ValidationError(error, code="bundled_skill_name")
return value
def validate_skill_file_path(value: str) -> str:
try:
return normalize_skill_file_path(value)
except ValueError as err:
raise serializers.ValidationError(str(err)) from err
def _validate_files(files: list[dict[str, Any]]) -> list[dict[str, Any]]:
if len(files) > MAX_SKILL_FILE_COUNT:
raise serializers.ValidationError(
f"A skill may contain at most {MAX_SKILL_FILE_COUNT} files.",
code="max_count",
)
paths = [f["path"] for f in files]
if len(paths) != len(set(paths)):
raise serializers.ValidationError("Duplicate file paths are not allowed.")
return files
def validate_skill_body_size(body: str) -> str:
body_bytes = len(body.encode("utf-8"))
if body_bytes > MAX_SKILL_BODY_BYTES:
raise serializers.ValidationError(
f"Skill body must be {MAX_SKILL_BODY_BYTES} bytes or fewer.",
code="max_size",
)
return body
def validate_allowed_tool(value: str) -> None:
# Returns None (raise-only) so it fits a DRF `validators=[...]` list.
try:
check_allowed_tool_name(value)
except ValueError as err:
raise serializers.ValidationError(str(err)) from err
class LLMSkillFetchQuerySerializer(serializers.Serializer):
version = serializers.IntegerField(
min_value=1,
required=False,
help_text="Specific skill version to fetch. If omitted, the latest version is returned.",
)
class LLMSkillBundleQuerySerializer(serializers.Serializer):
limit = serializers.IntegerField(
min_value=1,
max_value=MAX_BUNDLE_SKILLS,
default=DEFAULT_BUNDLE_SKILLS,
help_text=(
f"Maximum number of skills in the zip, newest first; default {DEFAULT_BUNDLE_SKILLS}, at most "
f"{MAX_BUNDLE_SKILLS}. Every skill in the zip costs the agent prompt context on each turn, so pick "
"what the harness can usefully carry. Skills past the limit are reported in X-Skills-Dropped."
),
)
content = serializers.ChoiceField(
choices=["stub", "full"],
default="stub",
help_text=(
"What each skill directory in the zip contains. 'stub' (default) writes a SKILL.md with the name, "
"description and instructions to fetch the skill over the PostHog MCP when it is invoked. 'full' writes "
"the rendered SKILL.md, every bundled file and the Codex sidecar."
),
)
class LLMSkillBodyFetchQuerySerializer(LLMSkillFetchQuerySerializer):
"""Fetch-by-name query params plus optional body paging — only the body-returning endpoint uses these."""
body_offset = serializers.IntegerField(
min_value=0,
required=False,
help_text="Zero-based character offset to start the returned body from. Use with body_length to page through a "
"large body that a client would otherwise truncate. Compare the returned body length against body_total_length "
"to detect truncation, then re-fetch from body_next_offset. Defaults to 0 (start of body).",
)
body_length = serializers.IntegerField(
min_value=1,
required=False,
help_text="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.",
)
class LLMSkillListQuerySerializer(serializers.Serializer):
search = serializers.CharField(
required=False,
allow_blank=True,
help_text="Optional substring filter applied to skill names and descriptions.",
)
created_by_id = serializers.IntegerField(
required=False,
help_text="Filter skills by the ID of the user who created them.",
)
owner_id = serializers.IntegerField(
required=False,
help_text="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.",
)
category = serializers.CharField(
required=False,
allow_blank=True,
help_text='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.",
)
class LLMSkillSearchQuerySerializer(serializers.Serializer):
query = serializers.CharField(
min_length=1,
max_length=200,
trim_whitespace=True,
help_text="Case-insensitive substring to search across ordinary skill names, descriptions, bodies, file paths, and Markdown file contents.",
)
class LLMSkillSearchMatchSerializer(serializers.Serializer):
matched_field = serializers.ChoiceField(
choices=["name", "description", "body", "file_path", "file_content"],
help_text="Skill field that matched the search query.",
)
path = serializers.CharField(
required=False,
help_text="Skill-relative file path for body or bundled-file matches. Omitted for name and description matches.",
)
line = serializers.IntegerField(
min_value=1,
required=False,
help_text="One-based line containing the match when the result came from a body or bundled file.",
)
excerpt = serializers.CharField(help_text="Short excerpt showing why this skill matched.")
class LLMSkillSearchResultSerializer(serializers.Serializer):
name = serializers.CharField(help_text="Unique skill name.")
description = serializers.CharField(help_text="What this skill does and when to use it.")
score = serializers.IntegerField(
min_value=1,
help_text="Relevance score used to rank this result. Higher scores are more relevant.",
)
matches = LLMSkillSearchMatchSerializer(
many=True,
help_text="Up to two locations that matched the search query, ordered by field relevance.",
)
@extend_schema_serializer(many=False)
class LLMSkillSearchResponseSerializer(serializers.Serializer):
count = serializers.IntegerField(help_text="Number of matching skills returned, capped at 10.")
results = LLMSkillSearchResultSerializer(many=True, help_text="Matching ordinary skills in relevance order.")
class LLMSkillSearchErrorSerializer(serializers.Serializer):
detail = serializers.CharField(help_text="Explanation of why the skill search could not complete.")
class LLMSkillResolveQuerySerializer(LLMSkillFetchQuerySerializer):
version_id = serializers.UUIDField(
required=False,
help_text="Exact skill version UUID to resolve.",
)
offset = serializers.IntegerField(
min_value=0,
required=False,
help_text="Zero-based offset into version history for pagination. Mutually exclusive with before_version.",
)
before_version = serializers.IntegerField(
min_value=1,
required=False,
help_text="Return versions older than this version number. Mutually exclusive with offset.",
)
limit = serializers.IntegerField(
min_value=1,
required=False,
default=DEFAULT_VERSION_PAGE_SIZE,
max_value=100,
help_text="Maximum number of versions to return per page (1-100).",
)
def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
if attrs.get("offset") is not None and attrs.get("before_version") is not None:
raise serializers.ValidationError("Use either offset or before_version, not both.")
return attrs
class LLMSkillOutlineEntrySerializer(serializers.Serializer):
level = serializers.IntegerField(min_value=1, max_value=6, help_text="Markdown heading level (1-6).")
text = serializers.CharField(help_text="Heading text.")
class LLMSkillSpecProblemSerializer(serializers.Serializer):
code = serializers.CharField(
help_text="Stable machine-readable code for the problem, e.g. description_too_long or file_path_collides."
)
message = serializers.CharField(help_text="What is wrong and what to change, written for the skill's author.")
file_path = serializers.CharField(
allow_null=True, help_text="The bundled file the problem is about. Null when it is about the skill itself."
)
class LLMSkillFileSerializer(serializers.ModelSerializer):
class Meta:
model = LLMSkillFile
fields = ["path", "content", "content_type"]
class LLMSkillFileManifestSerializer(serializers.ModelSerializer):
line_count = serializers.IntegerField(help_text="Number of lines in the file content.")
char_count = serializers.IntegerField(help_text="Number of characters in the file content.")
size = serializers.IntegerField(
allow_null=True,
help_text="Size of the file content in bytes. Null on rows written before digests were stamped.",
)
sha256 = serializers.CharField(
allow_null=True,
help_text="Hex SHA-256 of the file content. Null on rows written before digests were stamped.",
)
class Meta:
model = LLMSkillFile
fields = ["path", "content_type", "line_count", "char_count", "size", "sha256"]
class LLMSkillFileInputSerializer(serializers.Serializer):
path = serializers.CharField(
max_length=500,
help_text="File path relative to skill root, e.g. 'scripts/setup.sh' or 'references/guide.md'.",
)
content = serializers.CharField(
help_text="Text content of the file.",
)
content_type = serializers.CharField(
max_length=100,
required=False,
default="text/plain",
help_text="MIME type of the file content.",
)
def validate_path(self, value: str) -> str:
return validate_skill_file_path(value)
def validate_content(self, value: str) -> str:
if len(value.encode("utf-8")) > MAX_SKILL_FILE_BYTES:
raise serializers.ValidationError(
f"File content must be {MAX_SKILL_FILE_BYTES} bytes or fewer.",
code="max_size",
)
return value
class LLMSkillEditOperationSerializer(serializers.Serializer):
# Reused for both top-level body edits and per-file edits (LLMSkillFileEditSerializer.edits),
# so help_text must stay generic — the parent field's description provides the body/file context.
old = serializers.CharField(
help_text="Text to find in the target content. Must match exactly once.",
)
new = serializers.CharField(
allow_blank=True,
help_text="Replacement text.",
)
class LLMSkillFileEditSerializer(serializers.Serializer):
path = serializers.CharField(
max_length=500,
help_text="Path of the bundled file to edit. Must match an existing file on the current skill version.",
)
edits = LLMSkillEditOperationSerializer(
many=True,
help_text="Sequential find/replace operations to apply to this file's content.",
)
def validate_path(self, value: str) -> str:
return validate_skill_file_path(value)
def validate_edits(self, value: list[dict[str, str]]) -> list[dict[str, str]]:
if len(value) == 0:
raise serializers.ValidationError("At least one edit operation is required.")
return value
# The fields that publish a new skill version when present on a PATCH. A payload carrying none of
# these (owners only) replaces ownership without minting a version — the view branches on the same
# tuple, so keep the two in sync via this constant.
PUBLISH_CONTENT_FIELDS = (
"body",
"edits",
"description",
"license",
"compatibility",
"allowed_tools",
"metadata",
"files",
"file_edits",
"version_description",
)
class LLMSkillPublishSerializer(serializers.Serializer):
body = serializers.CharField(
required=False,
help_text="Full skill body (SKILL.md instruction content) to publish as a new version. Mutually exclusive with edits.",
)
edits = LLMSkillEditOperationSerializer(
many=True,
required=False,
help_text=(
"List of find/replace operations to apply to the current skill body. "
"Each edit's 'old' text must match exactly once. Edits are applied sequentially. "
"Mutually exclusive with body."
),
)
description = serializers.CharField(
max_length=SPEC_DESCRIPTION_MAX_LENGTH,
required=False,
help_text="Updated description for the new version.",
)
license = serializers.CharField(
max_length=255,
required=False,
allow_blank=True,
help_text="License name or reference.",
)
compatibility = serializers.CharField(
max_length=500,
required=False,
allow_blank=True,
help_text="Environment requirements.",
)
allowed_tools = serializers.ListField(
child=serializers.CharField(validators=[validate_allowed_tool]),
required=False,
help_text="Tools the skill asks to use. Tool names cannot contain whitespace. A harness that reads the "
"skill from a file (zip export, git marketplace, a content=full bundle) treats the list as pre-approved. "
"A harness that loads the skill over MCP, including the default content=stub bundle, ignores the list "
"until the user approves that grant.",
)
metadata = serializers.DictField(
required=False,
help_text="Arbitrary key-value metadata.",
)
files = LLMSkillFileInputSerializer(
many=True,
required=False,
help_text=(
"Bundled files to include with this version. Replaces all files from the previous "
"version. Mutually exclusive with file_edits."
),
)
file_edits = LLMSkillFileEditSerializer(
many=True,
required=False,
help_text=(
"Per-file find/replace updates. Each entry targets one existing file by path and "
"applies sequential edits to its content. Non-targeted files carry forward unchanged. "
"Cannot add, remove, or rename files — use 'files' for that. Mutually exclusive with files."
),
)
owners = serializers.ListField(
child=serializers.UUIDField(),
required=False,
max_length=MAX_SKILL_OWNERS,
help_text="Replace the skill's owners with these user UUIDs (each a member of this project). "
"Omit to leave owners unchanged; pass an empty list to clear them. Owners are keyed on the "
"logical skill, so setting them is independent of the version being published — a body edit "
"alone never changes ownership.",
)
base_version = serializers.IntegerField(
min_value=1,
required=False,
help_text="Latest version you are editing from. Used for optimistic concurrency checks. "
"Required when publishing content changes; optional for an owner-only update (when omitted, "
"owners are replaced without a concurrency check).",
)
version_description = serializers.CharField(
max_length=400,
required=False,
allow_blank=True,
help_text="Optional note describing what changed in this version. Shown in the version history.",
)
def validate_body(self, value: str) -> str:
return validate_skill_body_size(value)
def validate_version_description(self, value: str) -> str | None:
return value.strip() or None
def validate_edits(self, value: list[dict[str, str]]) -> list[dict[str, str]]:
if len(value) == 0:
raise serializers.ValidationError("At least one edit operation is required.")
return value
def validate_files(self, value: list[dict[str, Any]]) -> list[dict[str, Any]]:
return _validate_files(value)
def validate_file_edits(self, value: list[dict[str, Any]]) -> list[dict[str, Any]]:
if len(value) == 0:
raise serializers.ValidationError("At least one file_edits entry is required.")
paths = [entry["path"] for entry in value]
if len(paths) != len(set(paths)):
raise serializers.ValidationError("Duplicate file paths are not allowed in file_edits.")
return value
def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
if "body" in attrs and "edits" in attrs:
raise serializers.ValidationError("Provide either 'body' or 'edits', not both.")
if "files" in attrs and "file_edits" in attrs:
raise serializers.ValidationError("Provide either 'files' or 'file_edits', not both.")
# `base_version` is a plain optional field so the generated PATCH schema (which marks every
# body field optional) stays truthful for owner-only updates — but any payload that publishes
# a version still needs the optimistic-concurrency anchor, so require it here where the
# field-level schema can't.
is_owner_only = attrs.get("owners") is not None and all(attrs.get(f) is None for f in PUBLISH_CONTENT_FIELDS)
if not is_owner_only and attrs.get("base_version") is None:
raise serializers.ValidationError(
{"base_version": "base_version is required unless the update only sets owners."}
)
return attrs
class LLMSkillSerializer(serializers.ModelSerializer):
created_by = UserBasicSerializer(read_only=True)
is_latest = serializers.SerializerMethodField()
latest_version = serializers.SerializerMethodField()
version_count = serializers.SerializerMethodField()
first_version_created_at = serializers.SerializerMethodField()
allowed_tools = serializers.ListField(
child=serializers.CharField(validators=[validate_allowed_tool]),
required=False,
default=list,
help_text="Tools the skill asks to use. Tool names cannot contain whitespace. A harness that reads the "
"skill from a file (zip export, git marketplace, a content=full bundle) treats the list as pre-approved. "
"A harness that loads the skill over MCP, including the default content=stub bundle, ignores the list "
"until the user approves that grant.",
)
metadata = serializers.DictField(
required=False,
default=dict,
help_text="Arbitrary key-value metadata.",
)
category = serializers.CharField(
read_only=True,
help_text='Server-owned classification — set by the producing system (the Signals harness stamps "scout"), '
"not writable via the API. Empty for an ordinary skill. Groups skills into their own surface "
"(e.g. the Scouts tab) independently of the skill name.",
)
owners = serializers.SerializerMethodField(
help_text="Users who own this skill, seed-creator first. Ownership is keyed on the logical skill "
"(not a version), so it's stable across edits. Prefer this over created_by to learn who to route "
"reviews or questions to. Set via the owners field on create/update (a list of user UUIDs). "
"Empty for scout sandbox fetches of skills that haven't opted into the report channel.",
)
files = serializers.SerializerMethodField(
help_text="Bundled files manifest. Each entry carries path, content_type, and line/char counts — no content; fetch content via /llm_skills/name/{name}/files/{path}/.",
)
outline = serializers.SerializerMethodField(
help_text="Flat list of markdown headings parsed from the skill body. Useful as a lightweight table of contents.",
)
spec_problems = serializers.SerializerMethodField(
help_text="Why this skill is left out of the skills bundle and the plugin marketplace, as stable codes with "
"author-facing messages. Empty when the skill packages cleanly.",
)
body_total_length = serializers.SerializerMethodField(
help_text="Total length of the full body in characters, independent of any body_offset/body_length paging. "
"Compare against the length of the returned body to detect a truncated response.",
)
body_next_offset = serializers.SerializerMethodField(
help_text="When body_length paging stops before the end of the body, the character offset to request next "
"(pass as body_offset). Null when the returned body reaches the end.",
)
class Meta:
model = LLMSkill
fields = [
"id",
"name",
"description",
# Body-paging metadata is ordered before `body` so it survives a client that
# truncates the tail of a large response — the truncation signal stays readable.
"body_total_length",
"body_next_offset",
"body",
"license",
"compatibility",
"allowed_tools",
"metadata",
"category",
"owners",
"files",
"outline",
"spec_problems",
"version",
"version_description",
"created_by",
"created_at",
"updated_at",
"deleted",
"is_latest",
"latest_version",
"version_count",
"first_version_created_at",
]
read_only_fields = [
"id",
"owners",
"files",
"outline",
"spec_problems",
"body_total_length",
"body_next_offset",
"version",
"version_description",
"created_by",
"created_at",
"updated_at",
"deleted",
"is_latest",
"latest_version",
"version_count",
"first_version_created_at",
]
extra_kwargs = {
# No bundled-name rule here: this base serves the read responses, and a project's
# seeded canonical skills come back under the names PostHog ships. The write
# serializers carry that rule.
"name": {
"help_text": "Unique skill name. Lowercase letters, numbers, and hyphens only. Max 64 characters."
},
# No max_length here: this base serves read responses, and legacy rows can hold up to the
# 4096 column limit, above the 1024 spec cap. Deriving max_length from the model keeps the
# read schema honest about what the server returns. The 1024 write cap lives on the write
# serializers (LLMSkillCreateSerializer and LLMSkillPublishSerializer).
"description": {
"help_text": "What this skill does and when to use it.",
},
"body": {"help_text": "The SKILL.md instruction content (markdown)."},
"license": {"help_text": "License name or reference to a bundled license file."},
"compatibility": {
"help_text": "Environment requirements (intended product, system packages, network access, etc.)."
},
"metadata": {"help_text": "Arbitrary key-value metadata."},
"version_description": {
"help_text": "Optional note describing what changed in this version. Set when the version is published."
},
}
def get_is_latest(self, instance: LLMSkill) -> bool:
return bool(getattr(instance, "is_latest", False))
def get_latest_version(self, instance: LLMSkill) -> int:
return int(getattr(instance, "latest_version", instance.version))
def get_version_count(self, instance: LLMSkill) -> int:
return int(getattr(instance, "version_count", 1))
def get_first_version_created_at(self, instance: LLMSkill) -> str:
value = getattr(instance, "first_version_created_at", instance.created_at)
if value is None:
value = instance.created_at
if isinstance(value, str):
return value
return value.isoformat().replace("+00:00", "Z")
@extend_schema_field(UserBasicSerializer(many=True))
def get_owners(self, instance: LLMSkill) -> list[dict[str, Any]]:
# Owner identities are member PII. A scout sandbox token only gets them on skills that
# opted into the report channel — owners exist to route `suggested_reviewers`, which only
# report-channel scouts have — mirroring how the run prompt gates its owners line.
if self.context.get("scout_sandbox_caller") and not (
SCOUT_REPORT_CHANNEL_TOOLS & set(instance.allowed_tools or [])
):
return []
# The list endpoint pre-resolves owners for the whole page (one query) and passes them via
# context to avoid N+1; a single-skill fetch resolves on demand.
owners_by_name = self.context.get("owners_by_skill_name")
if owners_by_name is not None:
users = owners_by_name.get(instance.name, [])
else:
users = resolve_skill_owners(self.context["get_team"](), instance.name)
return list(UserBasicSerializer(users, many=True).data)
@extend_schema_field(LLMSkillFileManifestSerializer(many=True))
def get_files(self, instance: LLMSkill) -> list[dict[str, Any]]:
# Counts are computed in the database so the manifest never fetches file contents. The byte
# size comes from the stamped column rather than a `Length()` count, which counts characters.
annotated = LLMSkillFile.objects.filter(skill=instance).annotate(
char_count=Length("content"),
line_count=Length("content") - Length(Replace("content", Value("\n"))) + 1,
size=F("content_size"),
sha256=F("content_sha256"),
)
return [
dict(row) for row in annotated.values("path", "content_type", "line_count", "char_count", "size", "sha256")
]
@extend_schema_field(LLMSkillSpecProblemSerializer(many=True))
def get_spec_problems(self, instance: LLMSkill) -> list[dict[str, Any]]:
# Like owners: the list endpoint pre-resolves paths for the whole page (one query) and passes
# them via context to avoid N+1; a single-skill fetch reads them on demand. Paths only,
# because loading the relation would carry every bundled file's content the response drops.
paths_by_skill_id = self.context.get("file_paths_by_skill_id")
if paths_by_skill_id is not None:
paths = paths_by_skill_id.get(instance.id, [])
else:
paths = sorted(LLMSkillFile.objects.filter(skill=instance).values_list("path", flat=True))
return [asdict(problem) for problem in compute_spec_problems(instance.name, instance.description, paths)]
@extend_schema_field(LLMSkillOutlineEntrySerializer(many=True))
def get_outline(self, instance: LLMSkill) -> list[dict[str, Any]]:
return get_markdown_outline(instance.body)
def _body_offset(self) -> int:
return self.context.get("body_offset") or 0
@extend_schema_field(serializers.IntegerField())
def get_body_total_length(self, instance: LLMSkill) -> int:
return len(instance.body or "")
@extend_schema_field(serializers.IntegerField(allow_null=True))
def get_body_next_offset(self, instance: LLMSkill) -> int | None:
body_length = self.context.get("body_length")
if body_length is None:
return None
end = self._body_offset() + body_length
total = len(instance.body or "")
return end if end < total else None
def to_representation(self, instance: LLMSkill) -> dict[str, Any]:
data = super().to_representation(instance)
# Slice the body only when the caller asked to page through it — an ordinary
# fetch (no paging params) returns the whole body unchanged.
body = data.get("body")
if body is not None:
offset = self._body_offset()
body_length = self.context.get("body_length")
if offset or body_length is not None:
end = None if body_length is None else offset + body_length
data["body"] = body[offset:end]
return data
def validate_name(self, value: str) -> str:
return validate_new_skill_name_value(value)
def validate_body(self, value: str) -> str:
return validate_skill_body_size(value)
def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
team = self.context["get_team"]()
name = attrs.get("name")
if self.instance is None:
if name and LLMSkill.objects.filter(name=name, team=team, deleted=False).exists():
raise serializers.ValidationError({"name": "A skill with this name already exists."}, code="unique")
return attrs
if name is not None and self.instance.name != name:
# Renaming moves every version row and the owner rows together, which this path can't
# do — the dedicated rename endpoint owns it.
raise serializers.ValidationError(
{"name": "Use the rename endpoint to change a skill's name."},
code="immutable",
)
return attrs
class LLMSkillCreateSerializer(LLMSkillSerializer):
"""Create serializer — accepts bundled files and owners as write-only input on POST."""
# The write cap the base intentionally omits: new descriptions must clear the 1024 spec limit
# that community publish and export enforce.
description = serializers.CharField(
max_length=SPEC_DESCRIPTION_MAX_LENGTH,
help_text="What this skill does and when to use it. Max 1024 characters.",
)
files = LLMSkillFileInputSerializer( # type: ignore[assignment]
many=True,
required=False,
write_only=True,
help_text="Bundled files to include with the initial version (scripts, references, assets).",
)
owners = serializers.ListField( # type: ignore[assignment]
child=serializers.UUIDField(),
required=False,
write_only=True,
max_length=MAX_SKILL_OWNERS,
help_text="User UUIDs to set as the skill's owners. Each must be a member of this project. "
"Defaults to the creating user when omitted; pass an empty list to create with no owners.",
)
class Meta(LLMSkillSerializer.Meta):
read_only_fields = [f for f in LLMSkillSerializer.Meta.read_only_fields if f not in ("files", "owners")]
extra_kwargs = {
**LLMSkillSerializer.Meta.extra_kwargs,
"name": {
"help_text": "Unique skill name. Lowercase letters, numbers, and hyphens only. Max 64 characters. "
"Cannot be the name of a skill PostHog ships."
},
}
def validate_files(self, value: list[dict[str, Any]]) -> list[dict[str, Any]]:
return _validate_files(value)
def create(self, validated_data: dict[str, Any]) -> LLMSkill:
request = self.context["request"]
team = self.context["get_team"]()
files = validated_data.pop("files", None)
owner_uuids = validated_data.pop("owners", None)
validated_data["metadata"] = resolve_skill_metadata(validated_data.get("metadata"), None)
with transaction.atomic():
# `category` is read-only on the serializer, so it can never arrive in validated_data —
# the server-owned prefix stamp is the only writer.
skill = LLMSkill.objects.create(
team=team,
created_by=request.user,
is_latest=True,
category=category_for_skill_name(validated_data["name"]),
**validated_data,
)
if files:
LLMSkillFile.objects.bulk_create(
[
LLMSkillFile(
skill=skill,
path=f["path"],
content=f["content"],
content_type=f.get("content_type", "text/plain"),
)
for f in files
]
)
log_skill_activity(
team=team, user=request.user, item_id=str(skill.pk), skill_name=skill.name, activity="created"
)
# `is not None`, not truthiness: an explicit empty list means "create with no owners"
# and must not fall through to the creator-owns default (matching the update path).
if owner_uuids is not None:
try:
owner_users = resolve_owner_users(team, [str(u) for u in owner_uuids])
except LLMSkillOwnerNotFoundError as err:
raise serializers.ValidationError(
{"owners": f"User '{err.user_uuid}' is not a member of this project."},
code="invalid_owner",
)
set_skill_owners(team, skill.name, owner_users, acting_user=request.user)
else:
# Creator owns by default — durable, not reconstructed from version history.
seed_skill_owner(team, skill.name, request.user)
return skill
class LLMSkillListSerializer(LLMSkillSerializer):
"""List serializer that omits body and file manifest — progressive disclosure (Level 1)."""
class Meta(LLMSkillSerializer.Meta):
fields = [f for f in LLMSkillSerializer.Meta.fields if f not in _LIST_EXCLUDED_FIELDS]
read_only_fields = [f for f in LLMSkillSerializer.Meta.read_only_fields if f not in _LIST_EXCLUDED_FIELDS]
class LLMSkillVersionSummarySerializer(serializers.ModelSerializer):
created_by = UserBasicSerializer(read_only=True)
class Meta:
model = LLMSkill
fields = [
"id",
"version",
"version_description",
"created_by",
"created_at",
"is_latest",
]
read_only_fields = fields
class LLMSkillImportSerializer(serializers.Serializer):
file = serializers.FileField(
help_text="A spec-compliant skill .zip (a SKILL.md plus optional bundled files under scripts/, references/, assets/).",
)
class LLMSkillDuplicateSerializer(serializers.Serializer):
new_name = serializers.CharField(
max_length=64,
help_text="Name for the duplicated skill. Must be unique, and cannot be the name of a skill PostHog ships.",
)
def validate_new_name(self, value: str) -> str:
return validate_new_skill_name_value(value)
class LLMSkillRenameSerializer(serializers.Serializer):
new_name = serializers.CharField(
max_length=MAX_SKILL_NAME_LENGTH,
help_text="New name for the skill. Must be unique in the project, cannot be the name of a skill "
"PostHog ships, and must not start with 'signals-scout-' or 'review-hog-'.",
)
def validate_new_name(self, value: str) -> str:
return validate_new_skill_name_value(value)
class LLMSkillResolveResponseSerializer(serializers.Serializer):
skill = LLMSkillSerializer()
versions = LLMSkillVersionSummarySerializer(many=True)
has_more = serializers.BooleanField()
@extend_schema_field(
{
"type": "object",
"properties": {
"name": {"type": "string"},
"description": {"type": "string"},
"license": {"type": "string"},
"compatibility": {"type": "string"},
"metadata": {"type": "object", "additionalProperties": {"type": "string"}},
"allowed-tools": {"type": "string"},
},
"required": ["name", "description", "metadata"],
}
)
class SkillFrontmatterField(serializers.DictField):
"""The Agent Skills frontmatter mapping, passed through with the spec's own key names.
``allowed-tools`` is hyphenated in the spec, so the mapping is served verbatim instead of
through declared fields: a client must be able to compare it to ``yaml.safe_load`` of the
block in ``content`` key for key.
"""
class LLMSkillMarkdownSerializer(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 SKILL.md was rendered from.")
content = serializers.CharField(
help_text=(
"The complete SKILL.md file: the YAML frontmatter block, a blank line, then the skill body. "
"Serve these bytes as the file; a digest must be taken over this exact string."
)
)
frontmatter = SkillFrontmatterField(
help_text=(
"The frontmatter block of content as a JSON object. Equal to yaml.safe_load of that block, "
"so a listing can carry the same fields the file carries."
)
)
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,
required=False,
help_text=(
"Latest version you are editing from. If provided, the request fails with 409 "
"when another write has landed in the meantime."
),
)
class LLMSkillFileRenameSerializer(serializers.Serializer):
old_path = serializers.CharField(
max_length=500,
help_text="Current file path to rename.",
)
new_path = serializers.CharField(
max_length=500,
help_text="New file path. Must not already exist in the skill.",
)
base_version = serializers.IntegerField(
min_value=1,
required=False,
help_text=(
"Latest version you are editing from. If provided, the request fails with 409 "
"when another write has landed in the meantime."
),
)
def validate_old_path(self, value: str) -> str:
return validate_skill_file_path(value)
def validate_new_path(self, value: str) -> str:
return validate_skill_file_path(value)
def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
if attrs["old_path"] == attrs["new_path"]:
raise serializers.ValidationError("new_path must differ from old_path.")
return attrs
class LLMSkillFileDeleteQuerySerializer(serializers.Serializer):
base_version = serializers.IntegerField(
min_value=1,
required=False,
help_text=(
"Latest version you are editing from. If provided, the request fails with 409 "
"when another write has landed in the meantime."
),
)
class LLMSkillMarketplaceIssueSerializer(serializers.Serializer):
rotate = serializers.BooleanField(
required=False,
default=False,
help_text=(
"Roll the existing marketplace credential to issue a fresh token, replacing the old one "
"(this invalidates any setup using the previous token). Ignored when no credential exists yet — "
"the first call always mints one. Only affects this user's own credential."
),
)
class LLMSkillMarketplaceCommandSerializer(serializers.Serializer):
status = serializers.ChoiceField(
choices=["absent", "exists", "created", "rotated"],
help_text=(
"absent: no credential yet. exists: one already exists (no token returned). "
"created: a new credential was just minted. rotated: the existing credential was rolled."
),
)
connected = serializers.BooleanField(
help_text="Whether this user already has a marketplace credential for the team's skill store."
)
plugin_name = serializers.CharField(help_text="The plugin name the command installs (Claude Code and Codex).")
marketplace_name = serializers.CharField(help_text="The marketplace name, used by the Codex install command.")
label = serializers.CharField( # type: ignore[assignment] # field name shadows Field.label (str); intentional
help_text="Label of this user's marketplace credential (a scoped Personal API Key)."
)
repo_url = serializers.CharField(help_text="The marketplace git repository URL, with no credential embedded.")
command = serializers.CharField(
allow_null=True,
help_text=(
"Claude Code: ready-to-paste `/plugin marketplace add` command with the live token embedded. "
"Returned only when a token was just issued (status created/rotated); null otherwise."
),
)
command_template = serializers.CharField(
help_text="Claude Code install command with a YOUR_PHS_TOKEN placeholder instead of a live token; always present."
)
codex_command = serializers.CharField(
allow_null=True,
help_text=(
"OpenAI Codex: two-line `codex plugin marketplace add` + `codex plugin add` command with the live "
"token embedded. Returned only when a token was just issued (status created/rotated); null otherwise."
),
)
codex_command_template = serializers.CharField(
help_text="Codex install command with a YOUR_PHS_TOKEN placeholder instead of a live token; always present."
)
token = serializers.CharField(
allow_null=True,
help_text=(
"The raw read-only `phx_` credential. Returned once, only when minted or rotated; "
"it cannot be retrieved again afterwards."
),
)
mask_value = serializers.CharField(
allow_null=True, help_text="Masked preview of the existing credential (e.g. phx_...abcd)."
)
created_at = serializers.DateTimeField(allow_null=True, help_text="When the credential was created.")
last_rolled_at = serializers.DateTimeField(allow_null=True, help_text="When the credential was last rotated.")
class LLMSkillPublishToCommunitySerializer(serializers.Serializer):
expected_skill_id = serializers.UUIDField(
help_text="Immutable ID of the skill version that the publisher reviewed."
)
expected_version = serializers.IntegerField(
min_value=1,
help_text="Skill version that the publisher reviewed. The request returns 409 if the latest version changed.",
)
expected_category = serializers.CharField(
required=False,
allow_blank=True,
max_length=MAX_SKILL_CATEGORY_LENGTH,
help_text=(
"Category of the skill the publisher reviewed. Registering a skill as a scout changes its "
"category without raising its version, so the version alone would let a skill reviewed as "
"an ordinary one publish as a scout. The request returns 409 if the category changed. "
"Omit it to skip that check."
),
)
scout_config = CommunitySkillScoutConfigSerializer(
required=False,
help_text=(
"Schedule, emit posture and tags to publish alongside a scout, so it arrives in another project "
"with its cadence intact. Rejected for a skill that is not a scout."
),
)
display_name = serializers.RegexField(
DISPLAY_NAME_PATTERN,
required=False,
allow_blank=True,
max_length=MAX_DISPLAY_NAME_LENGTH,
help_text=(
"Human-friendly display name for the community listing. Defaults to a title-cased skill slug. "
"Must be a single line: it is used as the pull request title and commit message."
),
)
tags = serializers.ListField(
child=serializers.CharField(max_length=MAX_TAG_LENGTH),
required=False,
help_text="Tags used for filtering and discovery in the marketplace, e.g. ['web-analytics', 'triage'].",
)
author_handle = serializers.RegexField(
OPTIONAL_GITHUB_HANDLE_PATTERN,
required=False,
allow_blank=True,
# The pattern can't bound the total on its own: each of its repetitions may contribute a
# hyphen and a character, so it alone accepts 77 characters — not a username GitHub can hold.
max_length=MAX_GITHUB_HANDLE_LENGTH,
help_text=(
"The publisher's GitHub username, used for public attribution on the listing and PR. Optional, "
"and self-reported: it is not verified against the publisher's PostHog account."
),
)
class LLMSkillPublishConflictSerializer(serializers.Serializer):
detail = serializers.CharField(help_text="Reason that the reviewed skill version can no longer be published.")
class CommunitySkillPublishResultSerializer(serializers.Serializer):
pr_url = serializers.URLField(
help_text="URL of the pull request opened in the community-skills repo for maintainer review."
)
pr_number = serializers.IntegerField(help_text="Number of the opened pull request.")
branch = serializers.CharField(help_text="Name of the branch created in the community-skills repo.")