docs: strengthen the shared skill's proportionality rule - #1181
Merged
Conversation
Folds in the text from pipecat-ai/pipecat#5470, which is still open against pipecat's local SKILL.md and would otherwise be lost when that copy is retired in favour of this one. The version here had the substance but not two specifics worth keeping: the test for whether a note earns its place (judge it with the diff covered up — if it only makes sense as an explanation of what changed, it belongs in the changelog), and the worked example of a default moving from True to None, where the note is warranted only if None confuses someone meeting it for the first time. Also takes #5470's sharper wording for the changelog guideline and its checklist item, which names the failure directly rather than restating the principle.
Contributor
|
🔍 Mintlify preview for this branch: https://daily-docs-skill-proportionality-detail.mintlify.site |
This was referenced Aug 27, 2026
omChauhanDev
pushed a commit
to omChauhanDev/docs
that referenced
this pull request
Aug 31, 2026
The shared skill now lives in pipecat-ai/pipecat, published through the pipecat-dev-skills marketplace that already distributes that repo's other skills (pipecat-ai/pipecat#5471). That is the right home: six of the ten skills there are org-generic rather than pipecat-specific, so Cloud and client developers want the same plugin, and it is the repo that actually gets maintained. This directory was the first attempt at the same goal, hosting the skill here and leaving a pointer stub in pipecat. That stub would have shipped through the marketplace, since the plugin manifest sources skills from ./.claude/skills/*, giving anyone who updated the plugin a skill whose entire content was a path into a repo they may not have checked out. Nothing references these files any more: pipecat's workflow and skill are clean of the hosted path, and pipecat-flows still reads its own local copy. llms.txt and llms-full.txt are unchanged, confirming .md files here were never indexed. Reverts the content of pipecat-ai#1180 and pipecat-ai#1181. The proportionality rules pipecat-ai#1181 strengthened are preserved in the pipecat copy, verbatim apart from Prettier normalising one emphasis marker.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Small follow-up to #1180, and a prerequisite for retiring pipecat's local copy.
pipecat-ai/pipecat#5470 — "Keep update-docs edits proportional to the change" — is still open against pipecat's local
SKILL.md. That's the fix for #1168, where a one-line source change produced a page of re-litigation.When I extracted the shared skill I wrote the proportionality rule from memory of that diagnosis rather than from #5470's text. The substance came across; two specifics didn't:
The test for whether a note earns its place. #5470 gives a concrete one — judge it with the diff covered up. If the note only makes sense as an explanation of what changed, it belongs in the changelog. My version said callouts are "for behavior a reader would otherwise get wrong," which states the principle without giving anyone a way to apply it.
A worked example. A default moving from
TruetoNoneneeds the default updated; it needs a note only ifNoneconfuses someone meeting it for the first time — and then the note explainsNone, not the move. That distinction is the whole rule, and an abstract statement of it doesn't land.Also takes #5470's sharper wording for the changelog guideline — including why that failure survives the "write for a future reader" rule above it, which is that a justification carries no "newly" or "previously" to strip out — and its checklist item, which names the failure rather than restating the principle.
What this means for #5470
It's now fully superseded: everything it adds is here, in the copy that will be canonical once pipecat is repointed. Closing it rather than merging it avoids landing the same rules in a file that's about to be deleted — though merging it first is harmless if you'd rather keep the history in that repo.
Next PR is against pipecat: repoint its workflow at this skill, move its 26 repo-specific lines into its profile, and delete the local copy.
Verification
Prettier clean,
docs-meta-lint.mjs0 errors. No page content touched.🤖 Generated with Claude Code