postemi 1.0.0 → 1.1.0

package/skills/postemi-writing/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: postemi-writing
+description: Write social media posts people stop for and read to the end, then schedule them with Postemi. Covers finding post ideas, hooks and headlines, opening lines, formatting and rhythm, threads, the writing rules of each network (X, LinkedIn, Instagram, Threads, Bluesky, Facebook, TikTok, YouTube and more) and a check before publishing. Use when the user asks to write, rewrite or improve a post, thread, caption, hook or headline, asks what to post about, or wants a post to reach more people.
+---
+
+# Postemi writing: posts that get read
+
+This skill is about the words. Other Postemi skills sit next to it:
+
+- `postemi` (the main skill): the tools or commands that preview, schedule and
+  publish. Its rules win over anything here.
+- `postemi-templates`: ready post templates and hooks with [placeholders],
+  the same ones the Postemi composer shows. Start there when the user wants a
+  quick draft of a known type (a launch, a tip, a poll).
+- `postemi-growth` (optional, may not be installed): the plan over weeks: a
+  niche, a 30-day test, cadence per network, reading the numbers,
+  repurposing. If it is missing and the user wants a plan, tell them how to
+  add it (`postemi skills add growth`, or the `postemi-growth` plugin); ask
+  first, never install it yourself.
+
+Reference files in this skill:
+
+- [reference/headline-patterns.md](./reference/headline-patterns.md): 25 hook
+  and headline patterns with examples.
+- [reference/networks.md](./reference/networks.md): what works on each
+  network, and what Postemi does there.
+
+## Ground rules
+
+1. Write in the user's voice, about the user's real experience. Ask for facts
+   you do not have; never invent a number, a customer, a quote, a result or a
+   credential. A made-up detail is the fastest way to lose a reader's trust.
+2. A strong hook is fine only when the post pays it off. If the body cannot
+   keep the promise, make the hook smaller, never the truth bigger.
+3. Plain words, short sentences, one idea per post.
+4. Show the user the draft before anything is scheduled (the main skill's
+   preview step). The user decides; you suggest.
+
+## 1. Find the idea
+
+### The look-back test
+
+People who "have nothing to write about" are usually writing for the wrong
+reader. Ask the user three questions:
+
+- What did you not know two years ago that you know now?
+- What have you been through since then that you had not been through before?
+- Where were you two years ago, and where are you today?
+
+Every answer is a post. The reader is the person the user was two years ago:
+someone a step or two behind, who wants to hear from someone who just did it,
+not from a distant expert.
+
+### The idea builder: topic, proof, angle
+
+Build each idea from three choices.
+
+**Topic, made narrow.** Start broad, then go down at least two levels, then
+add who it is for and what they get:
+
+- Broad: cooking.
+- Narrower: cooking on weeknights.
+- Narrower still: cooking dinner in 20 minutes after work.
+- For whom, so that: for parents who get home at 6, so that the family eats
+  together without takeaway every night.
+
+The narrower the topic, the easier the post is to write and the quicker the
+right reader knows it is for them.
+
+**Proof: why should anyone listen?** Two kinds:
+
+- Own proof: "This is what happened to me." Lived experience needs no title;
+  say plainly that it is your experience.
+- Borrowed proof: what someone with the experience says or showed: a study,
+  a well-known practitioner, a customer, a book. Name the source honestly. On
+  X, links are removed, so name it in words.
+
+If the user has neither for a topic, pick another topic or borrow proof.
+
+**Angle: which road do you take the reader down?**
+
+| Angle | The post says | Example idea |
+|---|---|---|
+| How-to | Here is how to do it, step by step. | 5 steps to plan a week of dinners in 15 minutes |
+| Analysis | Here is what the data or the trend shows, and why. | Why grocery bills rose more for small households this year |
+| Inspiration | I did it, so you can too. | How I went from takeaway five nights a week to one |
+| Human nature | Here is the hidden human reason behind it. | Why we buy vegetables we never cook |
+
+Readers come back for the angle they liked. Try all four early; once the
+numbers show which one the user's audience prefers, lean on it. Mixing is
+fine later.
+
+### A short interview when the user has no idea yet
+
+Ask one question at a time, then offer three ideas, each with a hook:
+
+1. What do you do, and for whom?
+2. What question do people ask you most?
+3. What did you get wrong at the start?
+4. What do most people in your field believe that you disagree with?
+5. What happened this week that taught you something?
+
+For a whole month of ideas from one topic, use `postemi-growth` (30 angles)
+if it is installed.
+
+## 2. The hook
+
+The first line (or the title, on YouTube and blogs) decides whether anyone
+reads the rest. A good hook has these five qualities:
+
+1. **Clear, not clever.** A pun makes a friend smile and a stranger scroll
+   past. The reader must see at once what this is about and who it is for.
+2. **A promise.** Not only "this is about X" but "after reading, you will
+   have Y". No promise, no reason to give it 30 seconds.
+3. **Specific.** Name the problem, the reader, or both. Vague reads as
+   "not for me".
+4. **A stance.** Lean one way. The right reader thinks "this is exactly my
+   problem"; the wrong one thinks "not for me", and that is fine. A post for
+   everyone is a post for no one.
+5. **An open loop.** Say what they will get, hold back the answer. "Coffee
+   makes you anxious" gives it away; "The one coffee habit behind my 3 pm
+   anxiety" makes them read on.
+
+### Build the hook from six parts
+
+| Part | Question | Example |
+|---|---|---|
+| Number | How many things? | 4 |
+| Kind | Tips, mistakes, lessons, reasons, steps? | mistakes |
+| Topic | What exactly, two or three levels deep? | new runners make in their first month |
+| Reader | Who is it for? (often implied by the topic) | new runners |
+| Payoff | What does it get them, or save them from? | that lead to shin pain |
+| More stakes | What else is at risk or to win? | missed races, quitting by spring |
+
+Write the long version first, with every part:
+
+> 4 mistakes new runners make in their first month that lead to shin pain,
+> missed races and quitting by spring
+
+Then cut to fit the network: drop extra stakes first, then adjectives.
+
+> 4 first-month running mistakes that end in shin pain
+
+Starting long and cutting is easier than trying to be short and sharp at once.
+
+Ready patterns: [reference/headline-patterns.md](./reference/headline-patterns.md)
+and the hook groups in the `postemi-templates` skill. Offer the user two or
+three hooks for the same post and let them pick.
+
+### Where the hook has to land
+
+| Network | The hook is |
+|---|---|
+| X, Threads, Bluesky, Mastodon | the first line, and the first entry of a thread on its own |
+| LinkedIn | the first two or three lines, before "see more" |
+| Instagram | the first sentence of the caption (about 125 characters show), plus the image or the first second of the Reel |
+| TikTok, Reels, Shorts | the first one to three seconds and the on-screen text |
+| YouTube | the title (and the thumbnail the user makes) |
+| Facebook | the first line; long posts fold after a few lines |
+| WordPress, Ghost, Dev.to, Tumblr | the title |
+
+## 3. The first sentence: six openers
+
+Open with one sentence that does one of these:
+
+1. **A bold statement.** "Most small shops do not need a website. They need a
+   good photo on their map listing."
+2. **A question that makes them think.** "Why do the best bakers in town
+   never run out of bread at noon?"
+3. **A contrary opinion.** "Posting every day is bad advice for most
+   businesses."
+4. **A moment in time.** "At 6:40 on a Monday, our only oven died with 200
+   orders due."
+5. **An honest admission.** "For three years I priced my work too low and
+   called it being kind."
+6. **A surprising fact or detail.** "Our slowest product sells best on rainy
+   Tuesdays."
+
+Facts in openers must be true and, where it matters, sourced.
+
+## 4. Shape the post
+
+**Outline before writing.** Four lines, then fill them in:
+
+1. Working hook.
+2. One line of proof (why the user can say this).
+3. The main points (two to five).
+4. The takeaway (the one thing to remember or do).
+
+**Lead with the best part.** Do not make the reader wade through setup to
+reach the useful bit. Every line should earn the next.
+
+**Points that tell the story.** In a long post, a thread or a carousel, make
+each main point a line that reads well on its own, so a skimmer gets the
+whole story from the points alone. Use the points as section lines or as the
+first line of each thread entry.
+
+**The 1-3-1 rhythm.** Alternate a one-sentence paragraph with a paragraph of
+about three sentences, then a single line again. Vary sentence length the same
+way. It gives the reader a breath between ideas. On LinkedIn and Instagram,
+read mostly on phones, keep most paragraphs to one or two sentences.
+
+**End on purpose.** One of: a takeaway line, a question that is easy to
+answer ("Which of these did you make?"), or one call to action. Never three.
+
+**Text plus a picture or a video** usually beats text alone. Use the user's
+own photos and videos (Postemi uploads them; it does not generate images or
+video). A screenshot, a photo of the work or a short clip is enough.
+
+**Format.** Postemi post content is HTML: each line in `<p>`, plus `strong`,
+`ul`/`li` and `h1` to `h3` (never `u` and `strong` together). Networks show
+formatting differently; line breaks and short lists are safe everywhere. The
+preview shows the result.
+
+## 5. Formats
+
+- **Short post:** one idea, one to five lines. The daily bread on X, Threads
+  and Bluesky.
+- **Long post:** a hook, three to seven short paragraphs or a list, a
+  takeaway. Strong on LinkedIn and Facebook, and on X for accounts with a
+  higher character limit (the limit comes from the account, never guess it).
+- **Thread** (X, Threads, Bluesky): the first entry must work alone and make
+  people open the rest. One point per entry. The last entry sums up and asks
+  for a reply or a follow. Ask the user whether they want a thread or one long
+  post. On X, every thread entry counts toward the account's monthly X post
+  allowance in Postemi.
+- **Carousel** (LinkedIn image carousel, Instagram multi-image): one point per
+  slide, the hook on the first slide, the takeaway on the last. The user
+  supplies the images.
+- **Video caption** (TikTok, Reels, Shorts, YouTube): the caption supports
+  the video; the hook lives in the first seconds of the video itself.
+- **Post plus first comment** (LinkedIn, Facebook): put the main text in the
+  post and a link or extra detail in the first comment. In Postemi, the
+  entries after the first are comments on these networks.
+
+## 6. Network by network
+
+Short version; details in [reference/networks.md](./reference/networks.md).
+
+- **X:** short and direct; one X channel per post; no links (Postemi removes
+  them, so put the link in the bio or tell the user to post it on X
+  themselves); the character limit depends on the account; threads and every
+  entry count toward the monthly X allowance.
+- **LinkedIn:** the hook before "see more", short paragraphs, a question at the
+  end to draw comments; long text with an image, or an image carousel, does
+  well. Personal profiles only today (company pages are coming soon).
+- **Instagram:** the picture or Reel first, then a caption whose first sentence
+  hooks; a clear call to action; a few relevant hashtags. Reels want 9:16.
+- **Threads, Bluesky, Mastodon:** conversational, short; threads work.
+- **Facebook:** a friendly, local voice; questions and photos; links are fine.
+- **TikTok, YouTube:** the video carries it; write a caption and (YouTube) a
+  title that make a clear promise. TikTok takes about 15 posts per account per
+  day.
+- **Blog channels (WordPress, Ghost, Dev.to, Tumblr; beta):** a home for the
+  long version of the user's best posts, with a title.
+
+Never offer a network Postemi does not support (the main skill has the list;
+Pinterest, Google Business Profile and LinkedIn company pages are not
+schedulable yet).
+
+## 7. Check before publishing
+
+Go through this list for every draft, then show the user:
+
+1. The hook is clear, specific, promises something and leaves a question open.
+2. The body keeps the promise of the hook.
+3. The best part comes first; nothing is padding.
+4. Every fact, number and quote is true and came from the user or a named
+   source.
+5. One idea, one call to action at most.
+6. Short paragraphs; the 1-3-1 rhythm; it reads well on a phone.
+7. Every [placeholder] from a template is filled or removed.
+8. It fits the account's character limit (from the schema, not from memory).
+9. Network rules: no link in X posts; the LinkedIn hook sits above "see more";
+   media where the network needs it (Instagram, TikTok, YouTube).
+10. It sounds like the user, not like an advert. Read it aloud.
+11. Hashtags, if any: few and relevant. Emojis, if any: where the user would
+    use them.
+
+## 8. From draft to scheduled, with Postemi
+
+The workflow is always: **draft, preview, confirm, schedule.** The exact
+calls are in the main `postemi` skill; in short:
+
+Use whichever your client has. If the Postemi MCP tools are connected, use
+them and never install the CLI; the CLI is for agents with a terminal.
+
+With the Postemi MCP tools (Claude, ChatGPT, Cursor, Grok and other chat
+clients):
+
+1. `get_workspace_context` for the clock and the user's timezone.
+2. `list_integrations`; pick channels by id; say the `@handle` back.
+3. `get_integration_schema` for each channel: the real character limit and
+   the required settings. Write within them.
+4. `preview_post` with one `socialPost` entry per channel (each with its own
+   text, so every network gets its own version) and show the result.
+5. After the user says yes: `create_post` with the same payload and a new
+   `idempotencyKey`. `type: "draft"` saves without scheduling.
+
+With the `postemi` CLI (coding agents with a terminal):
+
+1. `postemi auth:status`, then `postemi integrations:list`.
+2. `postemi integrations:settings <id>` for the limit and the settings.
+3. Show the user the text per channel and the local time; wait for a yes.
+4. `postemi posts:create ... -t draft` to save, or with `-s "<date>"
+   --timezone <IANA>` to schedule; `--json` for different text per channel.
+   `postemi posts:find-slot <id>` suggests the next free slot.
+
+After it goes out, the numbers tell you which hooks and angles work: see
+`postemi-growth` (optional).

package/skills/postemi-writing/reference/headline-patterns.md

@@ -0,0 +1,109 @@
+# Hook and headline patterns
+
+25 patterns for a first line, a thread opener, a LinkedIn hook or a title.
+Brackets are slots. Each pattern has two made-up examples; write the user's
+own version, with their real topic, numbers and experience.
+
+Rules that hold for every pattern:
+
+- The body must deliver what the pattern promises. A list pattern needs the
+  full list; a "guaranteed" or "secret" pattern needs a real, specific answer.
+- Use real numbers only. "7 mistakes" means seven.
+- Cut to the network: long titles for blogs and YouTube, short hooks for X.
+
+## Problems and mistakes
+
+1. **[N] overlooked [things] behind your [problem]**
+   - 5 overlooked settings behind your slow laptop
+   - 3 overlooked habits behind your afternoon crash
+2. **The [N] biggest mistakes people make when [doing something]**
+   - The 6 biggest mistakes people make when they open a second shop
+   - The 4 biggest mistakes people make when they adopt a puppy
+3. **[N] in 10 people [have this problem]. Are you one of them?**
+   - 8 in 10 small online shops lose sales at checkout. Is yours one of them?
+     (only with a real source for the number)
+   - Most new managers skip one-to-ones in their first month. Are you one of
+     them?
+4. **How to get rid of [problem] for good, even if you have tried everything**
+   - How to stop procrastinating on invoices for good, even if you have tried
+     everything
+   - How to get rid of fruit flies in the kitchen for good, even if you have
+     tried everything
+5. **How [industry] takes advantage of [audience], and how to fix it**
+   - How phone contracts take advantage of older customers, and how to fix it
+   - How ticket fees take advantage of fans, and what organisers can do
+
+## How-to and guides
+
+6. **A step-by-step guide to [doing something]**
+   - A step-by-step guide to selling your first handmade candle online
+   - A step-by-step guide to running your first community meetup
+7. **How to [get a result] in [a short time]**
+   - How to tidy your inbox to zero in one afternoon
+   - How to learn the basics of a spreadsheet in a weekend
+8. **How to [get something good] without [giving up something you like]**
+   - How to save for a holiday without giving up your weekend coffee
+   - How to grow on LinkedIn without posting every day
+9. **The best ways to get [result] without needing [usual requirement]**
+   - The best ways to get your first clients without a portfolio
+   - The best ways to eat well on a budget without meal prepping all Sunday
+10. **The complete guide to [topic]**
+    - The complete guide to renting your first flat
+    - The complete guide to starting a vegetable patch on a balcony
+11. **Want [result]? Try [this one thing]**
+    - Want more replies to your cold emails? Try this two-line opener
+    - Want calmer mornings? Try packing the bag the night before
+12. **How to survive your first [big experience]**
+    - How to survive your first trade fair as an exhibitor
+    - How to survive your first week as a team lead
+
+## Lessons and stories
+
+13. **[N] lessons from [doing something hard or long]**
+    - 7 lessons from running a bakery for 10 years
+    - 5 lessons from my first 100 customer calls
+14. **A day in the life of a [profession]**
+    - A day in the life of a hospital night porter
+    - A day in the life of a one-person design studio
+15. **[Insight], from someone who does it for a living**
+    - Why restaurant prices keep rising, from a restaurant owner
+    - What makes a CV stand out, from a recruiter who reads 200 a week
+16. **What [a credible kind of person] can teach us about [topic]**
+    - What an air traffic controller can teach us about focus
+    - What a chess coach can teach us about making decisions under pressure
+    (use a role, or a real person only when the user has a true, sourced
+    lesson from them)
+17. **Is [thing] worth it? My honest review**
+    - Are online courses worth it? My honest review after 12 of them
+    - Is a standing desk worth it? My honest review after a year
+
+## Secrets, surprises and science
+
+18. **The secret to [something people want]**
+    - The secret to a sourdough that rises every time
+    - The secret to meetings that end on time
+19. **The [N] things most people do not know about [topic]**
+    - The 7 things most people do not know about buying a used car
+    - The 5 things most people do not know about how app stores rank apps
+20. **Why [something happens], according to research**
+    - Why small talk feels exhausting, according to research
+    - Why we remember the end of a holiday most, according to research
+21. **[N] things your [detail] says about you**
+    - 5 things your email signature says about your business
+    - 3 things your shop window says to people walking past
+22. **A reliable way to [get or avoid something]**
+    - A reliable way to never miss a tax deadline
+    - A reliable way to avoid scope creep on client projects
+    (stronger words like "guaranteed" only when it truly is)
+23. **How to make good money [doing something unexpected]**
+    - How a weekend bike repair stall became a full-time income
+    - How to earn a living cleaning solar panels
+
+## Lists and resources
+
+24. **The [N] best [books, tools, podcasts] if you want to [goal]**
+    - The 5 best books if you want to write clearer emails
+    - The 4 best free tools if you run a one-person shop
+25. **[N] tips for [getting past an obstacle]**
+    - 6 tips for staying active when you work from home
+    - 4 tips for asking for a raise when you hate negotiating

package/skills/postemi-writing/reference/networks.md

@@ -0,0 +1,113 @@
+# Writing for each network
+
+What tends to work on each network, and what Postemi does there. Postemi's
+rules (character limits, required settings, the X rules) come from the
+account's schema and the main `postemi` skill; when this file and the schema
+disagree, the schema wins.
+
+The networks below are the ones Postemi publishes to today. Pinterest, Google
+Business Profile and LinkedIn company pages are coming soon and cannot be
+scheduled yet. Never plan posts for a network Postemi does not offer.
+
+## X
+
+- **Shape:** short posts of one idea; a thread for anything with steps or a
+  story; a longer single post only when the account's limit allows it (read
+  the limit from the schema; never assume the account has a paid tier).
+- **Hook:** the first line. In a thread, the first entry must work on its own.
+- **Links:** Postemi removes links from X posts and their threads, because X
+  charges for every post with a link. Put the user's link in their X bio, or
+  tell the user to post a link on X directly. Name sources in words.
+- **Allowance:** the account has a monthly number of X posts in Postemi; every
+  thread entry counts as one. Check what is left before planning a busy X
+  calendar; when it runs out, X posts can only be saved as drafts until it
+  resets.
+- **One X channel per post.** Two X accounts need two separate posts with
+  different text.
+- **Media:** text plus a picture or a short video tends to beat text alone.
+- **Settings:** who can reply is required (see the main skill).
+
+## LinkedIn
+
+- **Shape:** one post a day at most is plenty; long text with an image, or an
+  image carousel (`post_as_images_carousel`), does well. Pure text works when
+  the writing is strong.
+- **Hook:** the first two or three lines, before "see more". Put the promise
+  there, not a greeting.
+- **Paragraphs:** one or two sentences each; most people read on a phone.
+- **Two kinds of post work together:** insight posts about the user's field
+  (most of them) and human posts: a lesson learned the hard way, a funny
+  moment, a challenge (about one in three).
+- **Comments:** comments are what spreads a post beyond the user's network.
+  End with a question that is easy to answer, and remind the user to reply to
+  comments in the first hours.
+- **Links:** a link in the post can pull people off the feed. A common pattern
+  is the post on its own and the link in the first comment; in Postemi that is
+  the second entry of `postsAndComments`, which LinkedIn shows as a comment.
+- **Today:** personal profiles only; company pages are coming soon.
+
+## Instagram
+
+- **Shape:** the picture or the Reel carries the post. Feed post, carousel,
+  Reel or Story (`post_type` is required).
+- **Caption:** the first sentence (about 125 characters show) is the hook;
+  then two or three useful lines that keep its promise; then one call to
+  action (save, share, comment, the link in the bio).
+- **Reels:** vertical 9:16 video; the hook in the first one to three seconds;
+  on-screen text for people watching without sound.
+- **Hashtags:** a few relevant ones; they help people find the post.
+- **Links:** captions do not make links clickable; point to the link in the
+  bio.
+
+## Threads and Bluesky
+
+- **Shape:** short, conversational posts; threads for longer ideas; replies
+  matter. Bluesky's limit is short, so read it from the schema.
+- **Links:** allowed.
+
+## Mastodon (beta)
+
+- **Shape:** conversational; people value plain, useful posts and dislike
+  marketing tone. About 500 characters on mastodon.social; other servers set
+  their own limit (read it from the schema).
+
+## Facebook
+
+- **Shape:** a friendly, local voice; photos and short videos; questions
+  people can answer in a word. Links are fine.
+- **Comments:** entries after the first are comments in Postemi, useful for a
+  link or a follow-up detail.
+- **Story:** `post_type: "story"` with a picture or a video.
+
+## TikTok
+
+- **Shape:** the video is the post; the caption adds context and a question.
+- **Hook:** the first one to three seconds of the video.
+- **Volume:** TikTok accepts about 15 posts per account in 24 hours; spread
+  bigger batches over more days.
+- **Settings:** privacy and posting method are required.
+
+## YouTube
+
+- **Shape:** a title, a description and the video; Shorts are 9:16.
+- **Title:** clear promise, specific, front-load the topic words people
+  search for. The thumbnail is the user's.
+- **Settings:** a title and a type are required; ask the user about privacy.
+
+## Telegram, Discord, Slack, Google Chat, Microsoft Teams
+
+- **Shape:** messages to a community the user already has. Be direct: what
+  is new, why it matters to them, what to do. Discord and Slack need a channel
+  id from their `channels` tool.
+
+## WordPress, Ghost, Dev.to, Tumblr (beta)
+
+- **Shape:** the long version: a title that makes a promise, an opening line,
+  section headings that tell the story, a takeaway. A title is required on
+  WordPress, Ghost and Dev.to.
+- **Use:** republish the user's best long posts and threads here as articles,
+  so they keep working and can be found by search.
+
+## Pixelfed (beta)
+
+- **Shape:** picture first, like Instagram; a picture is required.