PostHog / PostHog/posthog

Bring the skills store description limit in line with the Agent Skills spec (1024 chars)

Open
#90,141 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement self-driving
Dominant language
Python
Stars
39.9k
Forks
3.4k
Avg merge
6h 51m
Merged PRs (30d)
232

Description

Is your feature request related to a problem?

The skills store accepts a description of up to 4096 characters, but the Agent Skills spec (https://agentskills.io/specification) caps it at 1024. The two limits only collide at publish time: a skill looks fine in the team store, then community publishing rejects it with Skill description must be 1024 characters or fewer to publish.

Today the 4096 limit is enforced everywhere a description is written, and the 1024 limit only on the way out:

  • products/skills/backend/models/skills.py:42LLMSkill.description = CharField(max_length=4096) (raised from a smaller limit in products/llm_analytics/backend/migrations/0027_increase_skill_description_max_length.py)
  • products/skills/backend/models/community_skills.py:31CommunitySkill.description also 4096
  • products/skills/backend/api/skill_serializers.py:305,505 and products/skills/frontend/skillConstants.ts:2 — API and UI validate against 4096
  • products/skills/backend/tools/skills.py:149 — the MCP skill-create / skill-update tool description tells agents <=4096 chars
  • products/skills/backend/marketplace/packaging.py:28SPEC_DESCRIPTION_MAX_LENGTH = 1024, applied by validate_for_export and by the publish check in products/skills/backend/api/community_publish_services.py:195

So nothing warns an author, or an agent writing a skill over MCP, until they try to publish. I hit it twice today on skills I had already scrubbed for publication. The house guidance for store skills also encouraged long descriptions ("the store allows 4096"), because that is what the tools say.

Describe the solution you'd like

Spec out bringing the store in line with the Agent Skills spec so the limit is one number, enforced where the text is written. Questions to settle:

  1. Where to enforce 1024. Model, serializer, frontend constant, and the MCP tool description should agree. The MCP tool description in particular is what agents read, so it should carry the real limit.
  2. Existing skills over 1024. Some already exceed it, so a hard cut at write time needs a path: block only new writes over the limit, warn on existing ones in the UI and in skill-get, or run a one-off report so owners can trim.
  3. Whether 4096 should survive at all. If there is a reason to keep a longer internal description (there is a metadata field for anything that is not the retrieval surface), say so explicitly; otherwise drop the 4096 constants so the two numbers cannot drift again.
  4. Publish-time feedback. Even with write-time enforcement, the publish dialog could show the count and a trim affordance rather than a rejection.

Describe alternatives you've considered

  • Leave 4096 and surface the 1024 limit earlier: a live character count with the spec limit in the skill editor, the limit in the MCP tool description, and a warning on skill-get when a description exceeds it. Cheaper, but the two numbers keep drifting.
  • Truncate on publish. Rejected: the description is the retrieval surface, and silently cutting the trigger phrases off the end is worse than a rejection.

Additional context

The spec's other frontmatter limits (name <=64, compatibility <=500) are already mirrored on the store side, so this is the one field where the store and the spec disagree.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the skill models in products/skills/backend/models/skills.py and community_skills.py, the serializer limits in products/skills/backend/api/skill_serializers.py, the frontend constant, and the MCP guidance in products/skills/backend/tools/skills.py. Compare them with marketplace/packaging.py and the community publish check, then settle the handling of existing descriptions over 1024 characters. Done means the chosen policy is documented and the model, API, UI, MCP, and publish behavior no longer disagree.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, typescript
Domain
api, backend, frontend, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.