Measured while implementing #10178. Filed unassigned; observation, not a claim on anyone's time.
skills/** ships to customer projects and is loaded whole into customer agent context windows. Counted on origin/main at 2866d5f97:
6 skills/objectstack-ai/SKILL.md
6 skills/objectstack-api/SKILL.md
14 skills/objectstack-automation/SKILL.md
17 skills/objectstack-data/SKILL.md
14 skills/objectstack-formula/SKILL.md
5 skills/objectstack-i18n/SKILL.md
3 skills/objectstack-platform/SKILL.md
3 skills/objectstack-pm-dispatch/SKILL.md
8 skills/objectstack-query/SKILL.md
15 skills/objectstack-ui/SKILL.md
1 skills/objectstack-upgrade/SKILL.md
92 references of the form #NNNN (e.g. initialStates(optional, #3165) gates INSERT, and the same id again inside that section's code comment). They point at this repo's private tracker: a customer, or a customer's agent, cannot resolve one. To that reader they are noise that looks like a citation.
Why this is a cost question and not a style one
scripts/check-skills-token-ratchet.mjs exists because of the maintainer ruling of 2026-08-21, verbatim and untranslated: 「10402 需要整体考虑 skills 的长度,不能为了一个小功能扩写很多。」 Its header states the principle this finding sits on — the catalog's length "is not a repo-hygiene question: it is a per-token cost paid again in every customer session, in every customer project, forever."
Under that gate's own convention (ceil(utf8 bytes / 4)), the ids are a small but permanent line item, and unlike prose they buy the paying reader nothing at all. Removing them is also the one edit that is always legal against a shrink-only ratchet.
Why it was not just fixed
It is a convention question about the whole published corpus, not a defect in one file. #10178 needed 2 bytes of headroom in objectstack-automation/SKILL.md and deliberately did not take them from these ids: deleting two of 92 would have left the corpus inconsistent and quietly settled a corpus-wide convention on a two-line docs card. It paid instead by deleting a code comment that restated the sentence above it and named the wrong object.
What a card here would decide
- Do published skills keep provenance ids at all? (An internal reader has
git log and the ADRs; the customer has neither.) - If they go, does anything stop them coming back — a rule in
check-doc-authoring.mjs's corpus scan, or a new narrow gate? - If they stay, say so somewhere, because right now the practice is a habit rather than a decision — and the
.claude/** side already has a maintainer ruling pointing the other way for repo-internal docs (2026-08-12, verbatim: 「处理 issue 时犯的错应该总结成经验,保留 issue id没有意义」).
⚠️skills/** is a governed surface, so whatever lands here is draft + human merge + review from os-zhuang, and each ceiling it lowers should be lowered in the same PR.
Measured while implementing #10178. Filed unassigned; observation, not a claim on anyone's time.
skills/**ships to customer projects and is loaded whole into customer agent context windows. Counted onorigin/mainat2866d5f97:92 references of the form
#NNNN(e.g.initialStates(optional, #3165) gates INSERT, and the same id again inside that section's code comment). They point at this repo's private tracker: a customer, or a customer's agent, cannot resolve one. To that reader they are noise that looks like a citation.Why this is a cost question and not a style one
scripts/check-skills-token-ratchet.mjsexists because of the maintainer ruling of 2026-08-21, verbatim and untranslated: 「10402 需要整体考虑 skills 的长度,不能为了一个小功能扩写很多。」 Its header states the principle this finding sits on — the catalog's length "is not a repo-hygiene question: it is a per-token cost paid again in every customer session, in every customer project, forever."Under that gate's own convention (
ceil(utf8 bytes / 4)), the ids are a small but permanent line item, and unlike prose they buy the paying reader nothing at all. Removing them is also the one edit that is always legal against a shrink-only ratchet.Why it was not just fixed
It is a convention question about the whole published corpus, not a defect in one file. #10178 needed 2 bytes of headroom in
objectstack-automation/SKILL.mdand deliberately did not take them from these ids: deleting two of 92 would have left the corpus inconsistent and quietly settled a corpus-wide convention on a two-line docs card. It paid instead by deleting a code comment that restated the sentence above it and named the wrong object.What a card here would decide
git logand the ADRs; the customer has neither.)check-doc-authoring.mjs's corpus scan, or a new narrow gate?.claude/**side already has a maintainer ruling pointing the other way for repo-internal docs (2026-08-12, verbatim: 「处理 issue 时犯的错应该总结成经验,保留 issue id没有意义」).skills/**is a governed surface, so whatever lands here is draft + human merge + review from os-zhuang, and each ceiling it lowers should be lowered in the same PR.