Bring the skills store description limit in line with the Agent Skills spec (1024 chars)
Nobody has claimed this yet.
- 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:42—LLMSkill.description = CharField(max_length=4096)(raised from a smaller limit inproducts/llm_analytics/backend/migrations/0027_increase_skill_description_max_length.py)products/skills/backend/models/community_skills.py:31—CommunitySkill.descriptionalso 4096products/skills/backend/api/skill_serializers.py:305,505andproducts/skills/frontend/skillConstants.ts:2— API and UI validate against 4096products/skills/backend/tools/skills.py:149— the MCPskill-create/skill-updatetool description tells agents<=4096 charsproducts/skills/backend/marketplace/packaging.py:28—SPEC_DESCRIPTION_MAX_LENGTH = 1024, applied byvalidate_for_exportand by the publish check inproducts/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:
- 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.
- 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. - Whether 4096 should survive at all. If there is a reason to keep a longer internal description (there is a
metadatafield for anything that is not the retrieval surface), say so explicitly; otherwise drop the 4096 constants so the two numbers cannot drift again. - 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-getwhen 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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