ITADN

[docs] Skill size budget in write-a-skill.md (200/500) contradicts downstream enforcement (bluefin caps at 180)

#948Opencastrojo 创建于 23 天前
3-clanker-queue
C
castrojocommented
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 条评论