[docs] Skill size budget in write-a-skill.md (200/500) contradicts downstream enforcement (bluefin caps at 180)
3-clanker-queue
Found during a documentation audit of `projectbluefin/bluefin`.
## Finding
`docs/skills/write-a-skill.md` states the skill size budget as:
> - **Soft max:** 200 lines.
> - **Hard max:** 500 lines.
But the enforced contract downstream in `projectbluefin/bluefin` is a single hard cap of **180 lines**:
```python
# bluefin/.github/scripts/validate-docs.py:139
if len(text.splitlines()) > 180:
error(f"{skill.relative_to(ROOT)} exceeds 180 lines")
```
That script runs as a blocking `pre-commit` hook in bluefin, so an author following common's documented 200-line soft max writes a skill that fails validation in bluefin.
The same file also caps `AGENTS.md` at 150 lines and `docs/skills/index.md` at 80 — neither number appears anywhere in common's guidance.
## Why this matters
`write-a-skill.md` is cross-repo guidance. An agent reading it in a downstream repo gets a number that is wrong for the repo it is working in, and only finds out at commit time.
## What "fixed" looks like
Either:
- **Converge:** pick one budget and make common's doc and bluefin's `validate-docs.py` agree; or
- **Scope it:** state in `write-a-skill.md` that 200/500 is the common-repo budget and that downstream repos may enforce tighter caps, with a pointer telling authors to check the local validator.
The second is probably right — bluefin's skills are directory-style (`SKILL.md` + `references/`) and a tighter cap is a reasonable local policy. It just needs to be stated rather than contradicted.
## Reproduce
```bash
gh api repos/projectbluefin/bluefin/contents/.github/scripts/validate-docs.py \
--jq .content | base64 -d | grep -n "180\|MAX_LINES"
```
Priority: impact low-to-medium (authoring friction, no shipped-image risk), effort low.
0 条评论