@cratis/pi 6.3.2 → 6.5.0

package/package/corpus/rules/profiles.md

@@ -115,7 +115,7 @@ JVM language conventions are `kotlin.md` and `java.md`.
 | Profile ID | Description |
 |---|---|
 | `cratis/documentation` | Reader-centered product docs, technical examples, release notes, and voice review |
-| `cratis/content` | Release notes, social feed posts, and voice review |
+| `cratis/content` | Release notes, social feed posts, voice review, content length, and developer marketing and distribution |
 | `cratis/review` | Code review, performance, security |
 | `cratis/studio` | Studio MCP safety guidance |
 | `cratis/cli` | CLI operations |

package/package/corpus/skills/cratis-content-length/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/package/corpus/skills/cratis-content-length/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: cratis-content-length
+description: Decide how long a piece of content should be, when to keep it short, when it earns more length, and where to split it, for feed posts, documents and carousels, video, social threads, community posts, blog articles, tutorials, newsletters and release notes. Use when planning, drafting or reviewing content length, or a batch whose lengths are all the same. Do not use for SEO scoring or authorship detection.
+license: MIT
+---
+
+# Content length
+
+Most length advice starts from a number and works backward. A post should be 1,300
+characters, an article should be 2,000 words, and the draft gets stretched or trimmed until
+it fits. The numbers usually come from someone else's audience, and they measure engagement
+rather than whether anyone could use what they read.
+
+Start from the reader. Someone opened this piece to do something: decide whether a tool
+fits, run a command, understand why a replay failed, find out what changed in a release. The
+piece is long enough when that reader can do it. Past that point each sentence costs them
+attention. Short of it, they go somewhere else to finish.
+
+Two things follow. A short piece carries one idea. If it needs a second idea to make sense,
+it is a longer piece or two pieces. And the evidence you have puts a cap on length. One
+observation won't carry a 2,000-word essay without padding, and a migration with four
+required steps won't fit in a 400-character post.
+
+The bands below are editorial starting points. None is a proven optimum, and several rest on
+weak evidence. The table says which.
+
+## Decide the length before drafting
+
+1. Name the reader's job in one sentence. "Understand why a projection rebuild is slow" is a
+   job. "Raise awareness of projections" gives you no way to tell when the piece is done.
+2. Count what the job needs: the ideas the reader must take away and the steps they must
+   perform. One idea and no steps is a short post. Three steps and a failure check is a
+   tutorial, whatever channel it ends up on.
+3. Choose the vehicle before the word count. Short post, document, article, tutorial, video
+   or release note: the vehicle decides the unit you count and which band applies.
+4. Draft to the job, then compare the draft with its band. Inside the band, move on. Outside
+   it, you need a reason you can say in one sentence.
+5. Exceeding a platform limit requires shortening or another vehicle. Don't compress the
+   draft until the steps stop working. At a soft trigger, review navigation and completeness;
+   keep the piece together when the reader's task justifies it.
+
+Count in the unit the channel counts. LinkedIn's limit, as third parties report it, counts
+characters including spaces, emoji and line breaks. X counts weighted characters, with special rules for emoji, URLs and some Unicode ranges; use its documented counter rather than ordinary string length. Bluesky
+limits graphemes and bytes separately, and Mastodon's limit depends on the instance. Video is
+seconds, documents are pages, and articles and tutorials are words.
+
+### When to go shorter
+
+- The piece makes a single distinction, such as the difference between two commands, and
+  one example shows it.
+- A maintained source already holds the depth. A post that points to a documentation page or
+  a runnable sample should give one useful finding in the post, then link the maintained
+  source for the full procedure or evidence.
+- The audience is cold. People who don't know the product won't read five paragraphs to learn
+  whether it concerns them.
+- The second half says the first half again, or the ending restates the opening as a lesson.
+
+### When it earns more length
+
+- A worked example the reader can follow from input to observed result.
+- A method. When you report a result, say how you got it, what you compared and what you
+  didn't control. Vercel's write-up of a 91% cut in P99 metadata lookup latency is long
+  because it walks through the experiments. Take them out and the number has nothing
+  behind it.
+- A counterargument or simpler alternative, with enough room to be fair to it.
+- A procedure that breaks if you cut a step: setup, the run, how to tell it worked, what to
+  do when it didn't, and cleanup.
+
+Don't pad to reach a band. No scene-setting paragraph, no closing summary, no second example
+that shows the same thing. And don't cut a required step, a version or a material limit to
+get under one. If the job doesn't fit the vehicle, change the vehicle.
+
+## Pilot bands by type
+
+A ceiling is either a **platform limit**, where the channel refuses more, or a **soft
+trigger**, where you stop and review navigation and completeness, and keep the piece together
+when the reader's task justifies it. Grades describe the source, not how
+sure the number is: Official is the platform's own documentation or rules, Vendor is an
+observational study of a tool vendor's users, Practitioner is guidance or a case example,
+and Small study is one channel or a small sample. **Weak** means no verified outcome study
+backs that number on that channel. It is still usable for planning.
+
+| Type | Pilot target | Ceiling | Shorter when / longer when | Evidence |
+| --- | --- | --- | --- | --- |
+| LinkedIn personal post | 500–1,300 characters for one point; 1,300–2,500 for an account with evidence | 3,000 characters, platform limit as reported by a third party; check the composer | One distinction / a real example, method or counterargument | LM-01–03, Vendor and Practitioner; personal profiles only, not causal |
+| LinkedIn company page post | 400–1,200 characters | 2,000 soft trigger; 3,000 reported limit | An update that points to a doc / scope or evidence the claim needs | LI-11, LM-03, LM-06; **Weak** |
+| LinkedIn document | 5–9 legible pages, one idea per page | 12 pages, soft split trigger; the upload allowance is not a target | One fact fits one image / distinct steps or trade-offs | LM-10–12, Small study and Practitioner; **Weak**, one channel and click-inflated |
+| LinkedIn native video | 20–60 seconds | 90 seconds, soft trigger for a feed clip | One visible action / a demonstrated sequence, captioned | LM-18, Vendor; **Weak**, hosted video, not feed video |
+| X post | 80–240 weighted characters | 280 weighted characters, platform limit for ordinary posts | One proposition / link an artifact instead of forcing a thread | LM-15, Official limit; **Weak** target |
+| Bluesky post | 80–260 graphemes | 300 graphemes and 3,000 bytes, platform limit | One observation / only self-contained context | LM-13, Official limit; **Weak** target |
+| Mastodon post | 80–350 characters | 500 characters by default; check the instance | Same as Bluesky | LM-14, Official default; **Weak** target |
+| Social thread | Each installment stands alone | No numeric ceiling; if it needs numbering to make sense, write an article | Rarely longer; see splitting below | No verified evidence; **Weak** |
+| Community answer (Reddit, GitHub Discussions, forums) | The direct answer, plus only the context or code the question needs | No numeric ceiling; follow the community's rules | You've answered already and can link / the asker needs a reproducible answer | No verified length evidence; **Weak** |
+| Hacker News | Not drafted by AI; see below | None set here | None set here | HC-13, HC-16, Official |
+| Blog article | Quick answer 500–900 words; argued essay 1,200–2,200 | 3,000 words, soft split and navigation trigger | One answer / evidence, method, examples, alternatives | DP-03, DP-17, Practitioner and case; **Weak** |
+| Technical tutorial | 1,000–2,500 words, end to end | 3,500 words, soft split trigger; never cut a required step | A bounded how-to / setup, result, failure check, cleanup, version caveats | DM-03, DM-23, Survey; **Weak** band |
+| Newsletter | 150–350 words for one update; 350–600 for a digest | 600 words, soft trigger to link out or split | One takeaway / distinct items readers asked for | No verified body-length evidence; **Weak** |
+| YouTube Short | 20–60 seconds | Check current YouTube Help before upload; no verified maximum here | One visible behavior / only if the result needs it | LM-18 as a proxy; **Weak** |
+| Long video or demo page | 5–15 minutes | 30 minutes, soft trigger for chapters or a split; training can run longer | One operation / architecture, setup and observed outcome | LM-19–20, Vendor; **Weak** transfer |
+| Release note and announcement | One or two sentences per change; announcement 250–600 words | No hard ceiling; split by job | Routine fixes / breaking behavior, affected versions, action, rollback limits | DP-25, Practitioner; **Weak** band |
+
+Sources, populations and dates for every ID are in
+[the length evidence](references/length-evidence.md), along with length claims that are
+folklore.
+
+A few rows need a closer reading:
+
+- **The LinkedIn personal band.** It comes from AuthoredUp's study of 372,126
+  personal-profile posts, where posts of 1,301–2,500 characters had about 27% higher
+  engagement than posts under 400. That is an association on personal profiles. It doesn't
+  show that length caused anything and says nothing about company pages, and the medians
+  barely move above 1,300 characters (2.61% to 2.67%). Treat it as permission to write long
+  when there is something to say.
+- **The fold.** Only about 140 characters on mobile and 210 on desktop show before "see
+  more", by third-party measurement. Put a complete proposition in that space whatever the
+  total length. The opening itself is covered in **cratis-social-feed-post**.
+- **LinkedIn media.** Posts lead with media by default, and a text-only post is a deliberate
+  choice recorded with the post. That is the Cratis editorial default and an open
+  hypothesis being measured, not a proven effect. For length, it means the text and the asset
+  divide the work: decide what the asset carries, write the text for what it doesn't, and
+  count a document's pages as part of its length. Every asset carries the Cratis mark, and
+  captures are framed, never stamped. The media and branding rules live in
+  **cratis-social-feed-post**.
+- **Release notes.** The split into exact-version note, migration guide and announcement
+  belongs to **cratis-release-notes**. Use the band here only to notice when one of them is
+  trying to do another's job.
+
+### Hacker News
+
+No length is set here for HN because AI doesn't write or edit anything Cratis posts there:
+titles, text or comments. HN's guidelines prohibit generated or AI-edited comments. Applying
+that to everything Cratis posts on HN is our own stricter policy, broader than what HN's text
+says. A person writes it. An agent may gather facts and links for that person to check.
+
+## Vary length across a batch
+
+Look at the last 10–20 pieces on one channel together. Write down each one's length in the
+channel's unit and sort the list. When nearly all of them land in the same narrow band, the
+batch reads as a template before anyone gets to the subject. Structural sameness in general is
+covered in **cratis-writing-voice-and-cadence**; this section is about length only.
+
+Fix the spread by subject. Don't pick lengths at random. Go back through the queue and run
+the procedure above for each piece. Some subjects are a single distinction and should be short.
+Some come with a worked example and should run long. A post padded to be this week's long one
+is worse than the template it replaces.
+
+For a LinkedIn account, pilot these mix targets:
+
+- In any 10 consecutive posts, at least two short one-idea posts under about 600 characters.
+- In the same 10, at least two longer worked-example or method posts over about 1,500
+  characters.
+- The rest in between, with no more than about half of the 10 inside any single
+  400-character window.
+- For media-led posts, page counts vary too. Not every document has eight pages.
+
+These are editorial targets to measure against, not optima. No study says two short posts in
+ten does anything for an account. Record the length with each post and revise the targets
+once you have a few months of your own results.
+
+The same idea applies elsewhere: mix quick how-tos with end-to-end tutorials, quick answers
+with argued essays, and single-update newsletters with digests. If the queue can't meet the
+mix because every planned subject has the same shape, the subject list is the problem. Take
+that to whoever owns the editorial plan rather than padding or trimming to hit the numbers.
+
+## Split long work
+
+Split where the reader's jobs divide. The midpoint of the word count is almost never one of
+those places.
+
+- **Canonical piece with native entry points.** The full article, tutorial or sample lives in
+  one maintained place with versions and limits. Each channel gets an entry point written for
+  it that is useful without the click: one finding, one image or document, and the link. Most
+  long work should go this way.
+- **Document post.** Use it when the material is a sequence of distinct steps or trade-offs,
+  one per page. Past about 12 pages, review whether it reads better as two documents or an
+  article; keep it together when the reader's task justifies it.
+- **Series.** Use it when the parts are separate jobs a reader might want on different days,
+  such as setup, then modeling, then operations. Each part names its job, works alone and
+  links to the others. No cliffhanger endings.
+- **Thread.** Only when every installment is worth reading alone. A thread that exists
+  because the copy didn't fit in one post is an article split into pieces nobody can find
+  again.
+
+## Shorten without losing a claim
+
+Cut in this order: the preamble, restatements and closing summaries, a second example that
+shows the same thing, background this reader already has, and optional depth that can move to
+the linked source.
+
+Leave alone the required steps, the version and environment, every material limit, every
+hedge that changes what the reader does, and the source of every number. After cutting,
+check that each identifier, number and limiting word from the longer draft survived. The
+check is described in **cratis-writing-voice-and-cadence**. If the piece still won't fit
+a platform limit after that, the vehicle is wrong.
+
+## Check whether the length worked
+
+Measure what readers did after reading. Useful signals are substantive
+comments (a question about the mechanism, a counterexample, someone saying they tried it),
+visits to the linked page or sample through tagged links, and task completion where the
+product already measures it lawfully. Engagement rate says little about length. Document
+engagement can include the clicks that advance pages, and a click to the next page tells you
+nothing about whether the reader understood it.
+
+Record length, unit, type and account with each piece. Compare within one account and across
+similar subjects, and report raw counts with their denominators alongside any rate. Ten or
+twenty posts is a small sample. Subject and timing can confound the comparison; these sources
+do not establish their effects relative to length. Treat a result that changes with one
+additional post as inconclusive. Write the
+question and what would answer it before the pilot starts.
+
+## Stop conditions
+
+- Stop and ask the owner when the reader's job can't be named in a sentence.
+- When the job can't be done inside a platform limit without cutting a step or a material
+  limit, split or change the vehicle. Past a soft trigger, keep the piece together when the
+  reader's task justifies it. If the owner still wants the band, report the conflict.
+- Require sources for empirical claims and platform limits; label unsourced editorial
+  targets as hypotheses.
+- Stop at Hacker News. A person writes anything posted there.
+- Planning or reviewing length never authorizes publishing, scheduling, uploading or
+  replying. An agent does none of these.

package/package/corpus/skills/cratis-content-length/references/length-evidence.md

@@ -0,0 +1,115 @@
+# Length evidence
+
+The sources behind the bands in the content length skill, as of 2026-09-25. Every entry was
+checked against its source page; where the original reading overstated a source, the
+corrected reading is the one given here. Platform limits and vendor figures change, so check
+the live page before relying on a number and correct this file when it moves.
+
+Grades describe the kind of source, not how certain the number is:
+
+- **Official:** the platform's own documentation, specification or rules. Strong evidence of
+  how the platform works. It doesn't show that a tactic helps.
+- **Vendor:** an observational study published by a tool vendor about its own users' posts.
+  It shows an association in that population. It doesn't show cause, and it doesn't cover the
+  whole platform.
+- **Small study:** one channel or a small sample, with topic and creative uncontrolled.
+- **Survey:** what respondents said about themselves, with the survey's own recruitment bias.
+- **Practitioner:** guidance or a worked case from a company or practitioner. Good for ideas,
+  not for numbers.
+
+## LinkedIn text
+
+| ID | Finding | Population and method | Date | Grade | Source |
+| --- | --- | --- | --- | --- | --- |
+| LM-01 | Posts of 1,301–2,500 characters had about 27% higher engagement than posts under 400 characters. Not causal, and not a company-page result. | 372,126 personal-profile posts with at least one impression, September 2025 to February 2026 | Published 2026-04-02, updated 2026-08-11 | Vendor | [AuthoredUp](https://authoredup.com/blog/linkedin-character-limit) |
+| LM-02 | Median engagement by length band: 2.10% at 1–400 characters, 2.24% at 401–700, 2.31% at 701–1,000, 2.44% at 1,001–1,300, 2.61% at 1,301–2,000, 2.67% at 2,001–2,500, 2.62% at 2,501–3,000. The curve is not monotonic. Cite the table; an interactive graphic on the same page shows 2.63% for the last band. | Same sample as LM-01 | 2026-08-11 update | Vendor | [AuthoredUp](https://authoredup.com/blog/linkedin-character-limit) |
+| LM-03 | A 3,000-character post limit "including spaces, emojis, and line breaks", and roughly 210 desktop or 140 mobile characters visible before "see more". These are third-party figures, not a LinkedIn specification, and the visible count varies by device. | Vendor documentation | 2026-08-11 update | Practitioner | [AuthoredUp](https://authoredup.com/blog/linkedin-character-limit) |
+| LM-06 | Socialinsider's LinkedIn benchmark covers business pages, a different population from the personal profiles in LM-01. | 1.3 million posts from 16,645 active business pages, January 2024 to December 2025 | 2026-03-16 | Vendor | [Socialinsider](https://www.socialinsider.io/social-media-benchmarks/linkedin) |
+| LM-08 | LinkedIn's ranking uses what members have "read, liked, commented on, returned back to, or simply scrolled past". The article names no rewarded post length. That silence doesn't prove length never matters. | Engineering description of the feed system | 2026-03-12 | Official | [LinkedIn Engineering](https://www.linkedin.com/blog/engineering/feed/engineering-the-next-generation-of-linkedins-feed) |
+| LI-11 | Median engagement was 3.81% for link posts and 3.18% for text posts. This compares formats. It doesn't compare a link in the body with a link in a comment. | Buffer's sample of over 52 million posts across ten platforms | 2026-03-05 | Vendor | [Buffer](https://buffer.com/resources/state-of-social-media-engagement-2026/) |
+
+## LinkedIn documents
+
+| ID | Finding | Population and method | Date | Grade | Source |
+| --- | --- | --- | --- | --- | --- |
+| LM-04 | Median LinkedIn engagement by format: 21.77% for document carousels, 7.35% video, 6.52% images, 3.81% link posts, 3.18% text. These are format medians, not length effects, and not causal. | Over 52 million posts across ten platforms, posted through Buffer | 2026-03-05 | Vendor | [Buffer](https://buffer.com/resources/state-of-social-media-engagement-2026/) |
+| LM-09 | An agency's analysis of its own LinkedIn channel. Useful as an example of a local experiment, not a platform rule. | 114 carousel and video posts from one account, January to December 2025 | 2025 data; page date not stated | Small study | [The SEO Works](https://www.seoworks.co.uk/downloads/data-led-analysis-of-linkedin-video-vs-carousels/) |
+| LM-10 | Average carousel engagement by page count: 53.6% at 7–9 pages, 50.4% at 4–6, 45.5% at 10 or more, 36.9% at 3 or fewer. Topic and design are not controlled, and the article's cognitive-load explanation is not tested by the table. | Same sample as LM-09 | 2025 data | Small study | [The SEO Works](https://www.seoworks.co.uk/downloads/data-led-analysis-of-linkedin-video-vs-carousels/) |
+| LM-11 | The agency counts clicks to advance pages in its carousel engagement rate. A high rate therefore doesn't show that anyone understood or acted on the content. | Measurement description in the same article | 2025 data | Small study | [The SEO Works](https://www.seoworks.co.uk/downloads/data-led-analysis-of-linkedin-video-vs-carousels/) |
+| LM-12 | Socialinsider suggests 8–12 pages with one idea per page, and lists a 300-page maximum for organic document posts against 2–10 cards for paid carousel ads. Third-party guidance, not a LinkedIn specification. An upload maximum is not an editorial target. | Vendor guide | 2026-08-31 | Practitioner | [Socialinsider](https://www.socialinsider.io/blog/linkedin-carousel/) |
+
+## Other feeds
+
+| ID | Finding | Date | Grade | Source |
+| --- | --- | --- | --- | --- |
+| LM-13 | Bluesky post text is limited to 300 graphemes and 3,000 bytes. The lexicon specification defines these as Unicode grapheme clusters and UTF-8 bytes. The linked file is on the main branch and not pinned to a revision. | Live, accessed 2026-09 | Official | [AT Protocol post lexicon](https://raw.githubusercontent.com/bluesky-social/atproto/main/lexicons/app/bsky/feed/post.json), [lexicon specification](https://atproto.com/specs/lexicon) |
+| LM-14 | Mastodon's documented limit is 500 characters by default. Individual instances can differ. | Live, accessed 2026-09 | Official | [Mastodon posting guide](https://docs.joinmastodon.org/user/posting/) |
+| LM-15 | X ordinary posts are limited to 280 weighted characters, with special counting for emoji, URLs and some Unicode ranges. The page doesn't cover paid longer-post features. | Live, accessed 2026-09 | Official | [X counting characters](https://docs.x.com/fundamentals/counting-characters) |
+
+## Video
+
+| ID | Finding | Population and method | Date | Grade | Source |
+| --- | --- | --- | --- | --- | --- |
+| LM-17 | Wistia's 2026 analysis combines a survey of more than 900 professionals with more than 13 million videos and 79 million viewing hours on Wistia. It is hosted video, not a sample of social feed video. | Survey plus hosted-video data | 2026-04-22 | Vendor | [Wistia statistics](https://wistia.com/learn/marketing/video-marketing-statistics) |
+| LM-18 | Wistia suggests under one minute for awareness and social use. Videos under a minute averaged 52% engagement, which Wistia explains as viewers typically watching about half the length. It is not a 52% completion rate. | Wistia-hosted videos | Article dated 2025-07-01, revised for the 2026 report | Vendor | [Wistia video length](https://wistia.com/learn/marketing/optimal-video-length) |
+| LM-19 | Wistia suggests 1–5 minutes for education and explanation, including product demos, and says viewers typically watch over half of educational and tutorial videos in that range. | Wistia-hosted videos | Same | Vendor | [Wistia video length](https://wistia.com/learn/marketing/optimal-video-length) |
+| LM-20 | Wistia suggests 5–30 minutes for motivated viewers in conversion and nurture contexts and reports a 9% average click-through rate in that band. Longer duration isn't shown to cause the clicks. | Wistia-hosted videos | Same | Vendor | [Wistia video length](https://wistia.com/learn/marketing/optimal-video-length) |
+
+## Articles, tutorials and release notes
+
+None of these sources measures length. They support the reasoning in the skill, not its
+numbers, which is why those rows are marked weak.
+
+| ID | Finding | Date | Grade | Source |
+| --- | --- | --- | --- | --- |
+| DP-03 | PostHog tells writers to decide who a post is for and how it will reach them before writing, and contrasts fast, spiky social traffic with slow, compounding search traffic. | Living handbook | Practitioner | [PostHog blog handbook](https://posthog.com/handbook/content/blogs) |
+| DP-17 | Vercel's engineering article walks through production experiments and reports a 91% reduction in P99 metadata lookup latency. That figure is for metadata lookup, not overall CDN latency. | 2026-09-10 | Practitioner (case) | [Vercel](https://vercel.com/blog/how-we-cut-cdn-metadata-lookup-latency-by-91-percent) |
+| DM-03 | In the 2025 Stack Overflow survey, technical documentation was the most used learning resource in the past year, at nearly 68% of respondents. The survey recruits mainly through Stack Overflow's own channels. | 2025 | Survey | [Stack Overflow 2025](https://survey.stackoverflow.co/2025/developers/) |
+| DM-23 | Developer Nation reports documentation as the leading onboarding resource, with 39.3% calling it essential when starting with a new technology. The page doesn't give this item's denominator. | 2025 | Survey | [Developer Nation DN29](https://www.developernation.net/developer-reports/dn29/) |
+| DP-25 | Linear advises writing changelog entries about things interesting to a reader rather than everything the team did. | 2020-05-18 | Practitioner | [Linear](https://linear.app/now/startups-write-changelogs) |
+
+## Hacker News
+
+| ID | Finding | Date | Grade | Source |
+| --- | --- | --- | --- | --- |
+| HC-13 | HN asks submitters to use the original source and, generally, the original title unless it is misleading or linkbait. | Live | Official | [HN guidelines](https://news.ycombinator.com/newsguidelines.html) |
+| HC-16 | Under "In Comments", HN says: "Don't post generated text or AI-edited text. HN is for conversation between humans." The rule has no length exception. The quoted passage sits in the comment section and does not itself cover link submissions; Cratis applies it to everything it posts on HN as its own stricter policy. | Live | Official | [HN guidelines](https://news.ycombinator.com/newsguidelines.html) |
+
+## Batch variety and measurement
+
+| ID | Finding | Date | Grade | Source |
+| --- | --- | --- | --- | --- |
+| HV-06 | In the genres and models studied, LLM-written text struggled to match the stylistic variation of human writing. An aggregate finding; it can't classify a single post. | 2025-02-25 | Peer-reviewed | [Corpus study](https://pmc.ncbi.nlm.nih.gov/articles/PMC11874169/) |
+| LI-13 | Within the same account, LinkedIn posts where the author replied had about 30% more engagement. Buffer says this is not causal. | 2026-03-05 | Vendor | [Buffer](https://buffer.com/resources/state-of-social-media-engagement-2026/) |
+| MD-01 | Tagged campaign URLs identify the source, medium and campaign of an arrival. They don't capture earlier influence. | Live | Official | [Google Analytics](https://support.google.com/analytics/answer/10917952) |
+| MD-12 | GitHub describes a star as a way to find a repository again later. A star alone doesn't show installation or use. | Live | Official | [GitHub Docs](https://docs.github.com/en/get-started/exploring-projects-on-github/saving-repositories-with-stars) |
+
+The batch mix targets in the skill (two short and two long posts in any ten, and so on) are
+Cratis editorial targets. No source in this file tests them.
+
+## Not verified here
+
+These came up during research but were not verified for this file. Don't cite them from
+memory; check the live source first and add an entry if it holds up.
+
+- Search engine statements about word count and ranking.
+- Current YouTube Shorts maximum length and YouTube retention definitions.
+- Published-article studies relating word count to engaged time, links or shares.
+- Older usability research on web scanning and reading rates.
+- Email benchmark data and any newsletter length study.
+- Socialinsider's quarterly LinkedIn format averages.
+
+## Folklore
+
+| Claim | What the evidence says |
+| --- | --- |
+| "Every post must be short." | Not supported as a rule. In AuthoredUp's personal-profile sample the shortest band had the lowest median engagement (LM-02). That is an association, and a short post is still right for one idea. |
+| "1,300–2,500 characters wins the algorithm." | Not supported. The longer-band result is personal profiles only and not causal (LM-01), and LinkedIn's ranking description names no rewarded length (LM-08). |
+| "Company pages should copy what works on personal profiles." | The length study covers personal profiles only (LM-01). Business-page benchmarks are a different population (LM-06). |
+| "A high carousel engagement rate means people read it." | Page-advance clicks can count as engagement (LM-11). |
+| "LinkedIn accepts 300-page documents, so length doesn't matter." | An upload maximum reported by a third party (LM-12). It isn't an editorial target. |
+| "Seven to nine slides is the proven optimum." | One agency's channel, 114 posts, uncontrolled topic and design (LM-09, LM-10). |
+| "52% of viewers finish short videos." | Wistia's 52% is the average share of a video's length watched, on hosted video (LM-18). |
+| "Videos over a minute fail." | Wistia suggests different lengths for different goals, up to 30 minutes for motivated viewers (LM-19, LM-20). |
+| "Longer videos cause more conversions." | Wistia's 9% click-through figure for 5–30 minute videos is observational (LM-20). |
+| "Short AI-edited comments are fine on HN." | HN's comment rule has no length exception (HC-16). |

package/package/corpus/skills/cratis-content-length/verification.json

@@ -0,0 +1,19 @@
+{
+  "skill": "cratis-content-length",
+  "input": "Our last ten LinkedIn posts are all about 1,200 characters. Plan the lengths for the next batch and say how long the tutorial we are linking to should be.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "Choose the vehicle before the word count" },
+    { "kind": "skill-contains", "value": "Count in the unit the channel counts" },
+    { "kind": "skill-contains", "value": "Don't pad to reach a band" },
+    { "kind": "skill-contains", "value": "A procedure that breaks if you cut a step" },
+    { "kind": "skill-contains", "value": "personal profiles only, not causal" },
+    { "kind": "skill-contains", "value": "soft split trigger; the upload allowance is not a target" },
+    { "kind": "skill-contains", "value": "Fix the spread by subject" },
+    { "kind": "skill-contains", "value": "at least two short one-idea posts under about 600 characters" },
+    { "kind": "skill-contains", "value": "These are editorial targets to measure against, not optima" },
+    { "kind": "skill-contains", "value": "Canonical piece with native entry points" },
+    { "kind": "skill-contains", "value": "AI doesn't write or edit anything Cratis posts there" },
+    { "kind": "skill-contains", "value": "An agent does none of these" }
+  ]
+}

package/package/corpus/skills/cratis-developer-marketing/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/package/corpus/skills/cratis-developer-marketing/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: cratis-developer-marketing
+description: Plan or review how developer-facing content earns real engagement and adoption - positioning with developers, choosing the canonical artifact and its channel-native entry points, community participation, founder and company voice, a cadence a small team can keep, and measurement that doesn't fake attribution. Use when planning a content program, a launch, a distribution plan, a channel choice, a measurement plan or a repurposing plan. Do not use for drafting a specific feed post (use cratis-social-feed-post), voice review (cratis-writing-voice-and-cadence), length decisions (cratis-content-length), release notes (cratis-release-notes) or code examples (cratis-technical-examples).
+license: MIT
+---
+
+# Developer marketing
+
+This skill is for the plan around the content: who it is for, where the full version lives,
+which channels get a native version of it, who answers the replies, and how anyone will know
+whether it helped. It does not write the post, the article or the sample. Other skills own
+those, and this one names them when the plan reaches that point.
+
+The evidence behind this skill is summarized in
+[playbook evidence](references/playbook-evidence.md), dated and graded. Most of it is
+survey data, vendor observation and company practice. None of it tells you what will work
+for a specific product, so the plan should say what it expects and how it will check.
+
+Nothing in a plan is published, scheduled or replied to by an agent. A person does all
+three.
+
+## How developers find and judge a tool
+
+Survey answers point the same way, though they come from different questions in different
+years and don't describe one funnel. Respondents learn from documentation more than from
+any other resource. When asked how they discover and research a tool to buy, most
+picked starting a free trial and asking developers they know. When asked what attracts them
+to a technology for work, APIs ranked first and quality second. When asked what makes them
+reject one, security or privacy concerns ranked first, then price, then a better
+alternative. AI integration ranked near the bottom of the attraction list, and more
+respondents distrusted the accuracy of AI tools than trusted it.
+
+These are stated preferences from self-selected samples, not measured purchases. They still
+say something useful about what a first encounter should offer:
+
+- the interface a developer would call, shown with real identifiers at a stated version;
+- what it does when things go wrong, not only on the happy path;
+- the limits, including the cases it doesn't handle;
+- a path the reader can run in minutes, with a visible result.
+
+A post that can only say "it's powerful" gives the reader nothing to try or forward to a
+colleague.
+
+The person who writes the code is often not the only one deciding. Reported influence over
+purchases varies a lot by role, and executives and engineering managers report the most. Plan two views of the same capability. The implementer gets
+runnable evidence. The person accountable for the decision gets an honest account of
+operational risk, migration, security scope, cost and support. Don't build separate
+funnels for them. On a small team the same person may need both views in one week.
+
+## Trust comes from specifics
+
+Developers have seen every adjective. What moves them is a command, a measured number with
+its method, a trade-off stated plainly, and a comparison that a user of the other tool would
+accept as fair.
+
+- Name the limitation in the sentence it limits.
+- Compare against the alternative a reader would actually consider, including "keep doing
+  what you do now". If you can't state the alternative's strengths, you aren't ready to
+  compare.
+- Give a number only with its method and scope. "P99 lookup latency for this path" is a
+  claim. "Faster" is decoration.
+- Leave out manufactured urgency ("before it's too late"), fake consensus ("everyone is
+  moving to...") and unattributed authority ("studies show").
+- Claims about AI features need extra proof, given how many developers report distrusting
+  AI output.
+
+## Openings that promise something true
+
+Several studies analyzed thousands of historical Upworthy headline experiments. They found
+that wording changes clicks, that more concreteness helped vague headlines
+and hurt ones that were already very concrete, and that linguistic features predicted the
+winning variant only a little better than chance. Negative words were associated with a
+small relative rise in click-through. None of them measured trust, reading or adoption, and
+the audience was not engineers evaluating a tool. A higher click-through rate tells you the
+opening was clicked. It says nothing about whether the reader felt misled afterward.
+
+So the opening makes a specific, truthful proposition about the subject and then delivers
+it. It names the problem or the result. It does not withhold the subject to force a click.
+
+Story shapes to consider when the material supports them:
+
+- A real incident or bug: the symptom, what you first assumed, how you found the cause,
+  the fix, and what still isn't solved.
+- Before and after: the code or model a reader writes today, then the changed version,
+  with what it costs.
+- A teardown with its method: what you measured, how, on what, and where the method is
+  weak.
+- A decision with its trade-offs: the options you considered, why you rejected them, and
+  what you gave up.
+
+Incident stories and "I was wrong" stories must be real, and the named author has to own
+them. Never invent a failure, a customer, a late night or a change of mind to give a piece a
+narrative arc. If a scenario is illustrative, say so in the text.
+
+## One canonical source, many entry points
+
+Work from the top down:
+
+1. A pillar: a recurring question the audience actually has.
+2. One canonical, owned source for each piece of it: a versioned article, tutorial or
+   documentation page that holds the full explanation, the runnable path and the limits.
+3. Channel-native derivatives: each one a complete, smaller insight written for its
+   channel, not a teaser and not the same text pasted everywhere.
+4. Community answers: replies to questions people are already asking, linking the
+   canonical source only when it answers them.
+
+Repurposing means taking the core idea into a new format. Crossposting means copying the
+same text. Plan for the first. A derivative should still be useful to someone who never
+clicks, and it should link the canonical source when the reader needs it, such as the
+runnable sample the post is about.
+
+Channel norms, in brief. Length and character limits are in **cratis-content-length**, and
+feed drafting is in **cratis-social-feed-post**.
+
+| Channel | What it is good for | Norms to respect |
+| --- | --- | --- |
+| LinkedIn | One insight for practitioners and decision-makers | Posts lead with media by default; text-only is a deliberate, recorded choice |
+| X, Bluesky | A single finding inside an ongoing conversation | Short, conversational, one idea per post |
+| Mastodon | Technical peers who expect context in the post | Each server has its own rules; alt text on every image |
+| Reddit | Answering a question a community asked | Read that subreddit's current rules first; say you work on the project |
+| Hacker News | Original technical work people can try or learn from | Human-written only (see below); original titles; never ask for votes |
+| dev.to, Hashnode | The complete tested piece for readers there | The full article, not a teaser; point to the canonical source |
+| YouTube | Behavior that needs to be seen: debugging, a sequence, a UI | Title and thumbnail match what the video shows |
+| Newsletter | Repeat contact with people who asked for it | One or a few things subscribers want; judge by replies and clicks, not opens |
+| Search and answer engines | People who arrive with a task | Descriptive titles, accurate current pages; AI referrals are undercounted |
+
+On LinkedIn, leading with media is the Cratis editorial default and an open hypothesis
+the team is measuring. It is not a proven cause of reach. Record the reason when a post
+goes out as text only, so the comparison stays honest.
+
+Every published Cratis media asset carries the Cratis mark: images, cards, document pages,
+every GIF frame, video and screenshots. Captures are framed, never stamped. This is a brand
+and attribution rule, not a growth claim. Placement details are in
+**cratis-social-feed-post**.
+
+Hacker News has its own rule. Its guidelines prohibit generated or AI-edited comments. Cratis
+applies that to everything it posts there, including titles, submission text and comments.
+HN's rule is written for comments, so the wider scope is Cratis's own, stricter policy. An assistant
+may collect facts and links for the person writing, and must not draft or edit what they
+post.
+
+## Founder and company accounts
+
+The two accounts do different jobs. The founder speaks from firsthand judgment: what they
+decided, what surprised them, what they would do differently. The company account speaks
+for reviewed product facts and maintained explanations, as the team that built them.
+
+One developer-tools company reports that, for it, content from individuals on LinkedIn
+performs better and reads as more earnest than brand content. That is one company's
+observation with no effect size. Don't assume a founder multiplier. Measure each account
+against its own history.
+
+Employees may share or comment when they have something to add from their own work. A
+colleague's reshare with a sentence about how they used the feature is real. Engagement
+pods, coordinated likes, scheduled "thanks for sharing" comments and requests for votes are
+not, and they are off limits.
+
+A founder post is written or approved by the founder, in their words. Never put an opinion
+or an experience in someone's mouth. See **cratis-writing-voice-and-cadence** for the rules
+on attributed writing.
+
+## Community participation
+
+Every community has its own members, habits and rules, and it was there before you arrived.
+Treat a thread as a conversation you join, with the same manners you'd expect from a
+visitor in your own project.
+
+- Answer the question that was asked, in full, in the thread. Link only if the link adds
+  something the answer can't hold.
+- Say you work on the project whenever you mention it.
+- Read and follow the venue's current rules. Being able to join a server does not grant
+  permission to promote in it.
+- Don't drop the same link into several communities on launch day.
+- Specialist groups often run on member-proposed problems. Bring a problem to work through,
+  not a pitch.
+- A project-adjacent venue such as GitHub Discussions needs someone who answers and marks
+  questions resolved. Don't open a new chat community until someone can moderate it.
+
+## Launches
+
+Keep the release separate from the launch. The product team ships when a change is ready
+and documented. The launch is a later, deliberate effort to explain it to people who
+haven't heard of it. Two developer-tools companies describe shipping features as soon as
+they are ready and then writing the full explanation for a launch moment. The person who
+built the feature is often the right one to write the technical piece and pick its channels.
+
+A launch plan names the canonical piece, the few derivatives, who is present to answer
+questions on launch day and the week after, and what would count as a good result.
+
+## Cadence a small team can keep
+
+Count the whole cost of a piece: verifying product claims, making and checking assets, alt
+text, answering replies, and updating the canonical page when the product changes. Then set
+a pace that covers all of it.
+
+There is no required frequency. One large vendor study associates two to five LinkedIn posts
+a week with more impressions per post than one, and it is observational. One
+developer-tools company says outright that it doesn't set arbitrary volume goals. Start
+with what the team can sustain, keep it steady for long enough to compare against itself,
+and change one thing at a time. A burst followed by weeks of silence is hard to measure and
+leaves replies unanswered.
+
+Replies are part of the work. The same vendor data associates author replies with higher
+engagement within an account and does not claim cause. Plan the time anyway. A technical
+question left unanswered under a post is also a reader who got stuck.
+
+## Measurement
+
+Measure a progression, keep each stage in its own column, and never add them together as if
+they counted the same people. The stages, what each metric does and does not mean, a
+scorecard template and a small-sample experiment design are in
+[measurement](references/measurement.md).
+
+A star is a bookmark. An impression is a render. A last click is where a visit came from,
+not what convinced anyone. Report the actual event and its denominator.
+
+## Folklore
+
+| Claim | Status |
+| --- | --- |
+| A link in the LinkedIn body kills reach, so always put it in the first comment | Unproved; format studies don't isolate link placement |
+| The first hour decides a post's fate | No disclosed cutoff |
+| Use exactly N hashtags, or saves outrank likes | No published weights or counts |
+| Carousels reach more developers and drive adoption | Observed engagement can include slide clicks; adoption not measured |
+| Founder posts get a fixed reach multiplier | One company's observation, no effect size |
+| Everyone should post two to five times a week | Observational association, not a prescription |
+| Negative or mystery hooks win with engineers | Historical news-site CTR only; not trust or adoption |
+| Documentation only matters after the sale | Developers report using docs to learn and onboard |
+| Stars, impressions, followers or last clicks equal adoption | Different events; report the real one |
+| Hacker News is a channel for polished promotional replies | Its rules prohibit generated comments and primarily promotional use |
+
+Sources are in [playbook evidence](references/playbook-evidence.md).
+
+## What a plan contains
+
+- The reader, their task, and the question the pillar answers.
+- The canonical source, its version, and who keeps it current.
+- Each derivative: channel, account, author, format, and the one insight it carries.
+- Community venues, with their current rules checked and the person who will answer.
+- The capacity it assumes, in hours, including replies and maintenance.
+- The claims that need product verification before anything is drafted.
+- A measurement hypothesis with a primary outcome, an observation window and a stop rule.
+
+## Stop conditions
+
+Stop and ask when the author of a first-person piece hasn't confirmed the experience, when a
+claim has no verified source, when a venue's rules are unknown, or when the plan depends on
+tracking that the site doesn't already have with consent. A plan authorizes nobody to
+publish, schedule, reply, tag or upload.