github / github/copilot-cli

SKILL.md files with description > 1024 chars are silently dropped from skills.list() — no warning, no error

Open
#3,494 0 comments 0 reactions 0 assignees View on GitHub
area:plugins
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.