diff --git a/AGENTS.md b/AGENTS.md index 5b8ffc6..50635a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,6 +124,7 @@ For specific workflows, load the matching skill under `ai-skills/` rather than i - `wm-ai-release-notes` — add or edit entries in a versioned release notes file under `docs/release-notes/`. - `wm-feature-announcements` — new post under `blogs/feature-announcements/`. +- `wm-ai-blog` — new narrative or thought-leadership post under `blogs/blog/`. - `wm-ai-create-guide` — create a how-to or tutorial page under `docs/guide/`. - `wm-ai-documentation` — write, update, move, or delete a core reference or conceptual doc under `docs/
/...` (interactive: outlines first, drafts section by section, handles assets, links, and sidebar wiring). diff --git a/ai-skills/wm-ai-blog/SKILL.md b/ai-skills/wm-ai-blog/SKILL.md new file mode 100644 index 0000000..52ab9cd --- /dev/null +++ b/ai-skills/wm-ai-blog/SKILL.md @@ -0,0 +1,152 @@ +--- +name: wm-ai-blog +description: > + Use this skill when writing a narrative engineering or thought-leadership blog post + under `blogs/blog/` for the WaveMaker docs site. Activate when the user wants a blog + post, an engineering story, a "how we built X" writeup, or an opinion/thought-leadership + piece for `/blog` — distinct from a feature announcement (short, public "we shipped X" + notice), release notes (versioned changelog), or a core doc (reference/how-to page). +license: MIT +metadata: + version: 0.1.0 + surface: blogs/blog + docusaurus: ^3.9.0 +--- + +# WaveMaker Blog Post + +Use this skill to author a new post on the main blog (`/blog`). Blog posts are longer, narrative pieces — engineering deep-dives, "how we built it" retrospectives, and thought-leadership arguments — distinct from the short public-facing notices on `/feature-announcements` and the versioned changelog in `docs/release-notes/`. + +## When to use + +- User wants to write a blog post, engineering story, or "how we built X" retrospective. +- User wants a thought-leadership or opinion piece published to `/blog`. +- User has a draft, notes, or a rough narrative and wants it turned into a publish-ready post. + +## When NOT to use + +- User wants a short, public "we shipped X" notice → use the `wm-ai-feature-announcements` skill. +- User wants a versioned, comprehensive list of changes in a release → use the `wm-ai-release-notes` skill. +- User wants a reference or conceptual doc page under `docs/` → use the `wm-ai-documentation` skill. +- User wants a step-by-step how-to or tutorial → use the `wm-ai-create-guide` skill. + +If the request is borderline (e.g., "write about the feature we shipped"), ask: "Is this a short public notice, or a longer story about how it works / how you built it?" The former is a feature announcement; the latter is a blog post. + +## Operating principles + +- **This skill is more editorially loose than its siblings.** There is no sidebar to wire and no required tab/accordion classification. The site only *warns* (doesn't fail the build) on an untruncated post, but this skill always places a `{/* truncate */}` marker regardless — ask the user where they'd like the preview to cut if the default (right after the hook) doesn't fit. Do not invent structure beyond that the codebase doesn't enforce. +- **Read 1–2 existing posts in `blogs/blog/` before drafting.** Tone, section rhythm, and component usage vary by author; match the nearest sibling rather than a fixed formula. +- **Outline first for long or multi-section posts.** For a short opinion piece, a single-shot draft is fine — ask the user which they want. +- **Confirm before writing.** Present the draft (or section-by-section, for a long post) and get confirmation before creating the file. +- **Verify everything you reference** — author keys, tags, doc/blog links, image and video paths — before writing them. See `references/conventions.md`. + +## Inputs to collect + +Ask these together, in one grouped message: + +1. **Title** — descriptive, can be a thesis statement or a question (e.g., "AI Guardrails vs Assembly Explained"). Sentence case or title case both appear in existing posts — match whichever the user prefers. +2. **Publish date** — `YYYY-MM-DD`. Defaults to today; this becomes the filename prefix and the post's URL date segments. +3. **Slug** — kebab-case, descriptive, used in the filename. +4. **Author key** — read `data/author/authors.yml` and list the existing authors (key + name) for the user to pick from. If they want someone not on the list, offer to add a new entry and ask for the details needed to do so: display `name`, `title`, profile `url`, `image_url`, and any `socials` (github/linkedin handles). Do not invent or guess any of these fields — add the entry only with what the user supplies. +5. **Source material** — draft text, notes, a Slack thread, or just a topic and a few bullet points. Treat the user's input as source-of-truth for facts; you handle structure and prose. +6. **Tags** (optional) — most existing posts carry no tags at all. Only add tags if the user wants them, and only reuse a key that already exists in `blogs/blog/tags.yml`. That file currently holds unrelated Docusaurus-starter placeholders (`facebook`, `hola`, `tutorial`, ...) — do not reuse those as if they were real topics; if the user wants a real tag, add a proper entry to `tags.yml` first and confirm with them. +7. **Media** (optional) — screenshots/diagrams, a local video file, or an Academy walkthrough/video URL. + +Do not start drafting until title, slug, and author are confirmed. + +## File layout + +```text +blogs/blog/YYYY-MM-DD-.mdx +``` + +Assets are co-located and shared across all posts in this plugin instance (not per-slug for images): + +```text +blogs/blog/assets/img/.png +blogs/blog/assets/videos//