SKILL.md files with description > 1024 chars are silently dropped from skills.list() — no warning, no error
- Dominant language
- Shell
- Stars
- 11.2k
- Forks
- 1.9k
- Avg merge
- 14h 16m
- Merged PRs (30d)
- 6
Description
### Environment
- Copilot CLI: `1.0.36-0`
- Python SDK: `github_copilot_sdk==0.3.0`
- OS: Windows 11
- Discovery method: `skill_directories=[...]` on `Session(...)`
### Problem
The [Agent Skills specification](https://agentskills.io/specification) states:
> `description: Max 1024 characters. Non-empty.`
The CLI enforces this cap correctly during skill load, but **silently**:
- Over-cap files are materialised on disk by the SDK loader.
- They are then dropped during YAML/frontmatter parse.
- No warning is emitted (`stderr`, log, or otherwise).
- No error is raised.
- The skill simply does not appear in `session.skills.list()`.
This is particularly painful for skills generated by tooling (we generate `description` from a keyword pool that grows as the codebase grows). The skill silently disappears between releases and there's no signal to debug.
### Reproducer
Save this as `bad-skill/SKILL.md` (description is 1,200 chars, deliberately over cap):
```markdown
---
name: bad-skill
description: AAAAAAAAAA[…repeat letter 'A' 1200 times…]
---
# Bad Skill
Body.
```
(Padding character + exact length is the only thing that matters; the body is irrelevant.)
Place the `bad-skill/` folder in the current directory, then:
```python
import asyncio
from copilot.session import Session
async def main():
async with Session(skill_directories=["."]) as s:
result = await s.rpc.skills.list()
print([sk.name for sk in result.skills])
asyncio.run(main())
# Expected: ["bad-skill"]
# Actual: [] (silent drop, no log)
```
Trim the description to ≤ 1,024 chars and the same call returns `["bad-skill"]`.
### Suggested fix
Emit a warning at load time the way the loader does for unknown frontmatter fields:
```
[warn] skill 'bad-skill' (./bad-skill/SKILL.md):
description exceeds 1024-char cap (got 1200); skill not loaded
```
Documenting the 1,024-char cap in [docs.github.com/copilot/concepts/agents/about-agent-skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) would also help — currently only the spec page mentions it.
### Workaround
Trim `description` under the cap before shipping. We've added a lint step that fails CI if any `SKILL.md` description ≥ 1024 chars.
Contributor guide
Assessment
This issue has not been assessed yet.