document360-engine 0.1.0

package/skills/write-article/SKILL.md

@@ -0,0 +1,95 @@
+# Skill: write-article
+
+**Activate when** the user asks to write, draft, or generate a specific article — by topic name, by file path, or by reference to the approved plan.
+
+**Goal:** produce one publishable article that follows the system-prompt article structure exactly, grounded in the actual source code, and with screenshot placeholders where the user benefits from seeing the UI.
+
+## Before writing — gather
+
+1. Read the source files relevant to this article. Don't skip this. The whole point of this tool is that articles are grounded in code.
+2. Read `AGENT-PLAN.md` if present, to confirm the article's purpose matches the approved plan.
+3. Read 1–2 existing articles in the same category, if any, to match voice and structure.
+4. If `gather-context-from-mcp` is appropriate (the user has connected Notion / GitHub / etc. and the article would benefit from external context), invoke it.
+
+## Article skeleton (system-prompt-mandated)
+
+```
+# <Article title>
+
+<one-paragraph intro>
+
+## Prerequisites
+- <role/permissions, if any>
+- <required state>
+
+## Steps
+1. ...
+2. ...
+
+## Tips & notes
+- ...
+
+## Related articles
+- ...
+```
+
+## Screenshot placeholders
+
+**Screenshots apply only to browser-reachable UIs.** If the product has none (CLI, console app, library, API-only service), emit NO screenshot placeholders and do not invoke `emit-screenshot-spec` — show behavior as fenced code blocks instead: the exact command, then its real terminal output (run it or quote it from source/tests; never invent output). Never fabricate a UI to screenshot.
+
+When the article describes a UI flow that benefits from a visual, embed one or more screenshot placeholders. Each placeholder is two parts:
+
+1. An HTML comment block with capture instructions (stripped before D360 publish).
+2. A visible `[Screenshot: ...]` line (kept in both local and D360).
+
+Example:
+
+```markdown
+<!-- SCREENSHOT
+id: <kebab-case-stable-id>
+title: "<short title>"
+page-url: <relative path or URL>
+prerequisites:
+  - <plain-English state setup>
+steps:
+  1. <numbered actions with EXACT button labels>
+capture: <full-page | main-panel | modal-only | panel-left | panel-right | sidebar>
+device: desktop
+viewport: 1440x900
+highlight:
+  - <thing to draw attention to>
+annotations:
+  - <numbered callouts with short text>
+redact:
+  - <regions to hide (emails, real tokens, etc.)>
+save-to: user-docs/_screenshots/<id>.raw.png
+auto-capture-script: user-docs/_capture/<id>.spec.ts
+notes:
+  - <edge cases>
+-->
+[Screenshot: <short reader-facing description>]
+> 🤖 Auto-capture: `d360-capture capture <id>`
+> Sign in to Chromium when prompted; the script does the rest.
+```
+
+Every field must be filled. If a field doesn't apply, write "none" or "n/a" — never omit.
+
+**The `prerequisites` and `steps` fields must be detailed enough for a junior intern to capture the screenshot without further instruction.** If you can't write them that clearly, you don't understand the screen well enough — read more source code.
+
+For every screenshot placeholder you generate, also invoke `emit-screenshot-spec` so the matching `.spec.ts` lands in `<captureDir>/<id>.spec.ts`.
+
+## Writing rules (re-emphasis from system prompt)
+
+- Second person, imperative. No marketing language. No "simply", "just", "easily".
+- Quote exact UI strings. Read the React/HTML/etc. source.
+- State role-gating in **Prerequisites**, not in Steps.
+- Markdown only. One H1.
+
+## Output
+
+Write the article directly to its file path. Do not paste the markdown into the chat; the user wants the file on disk so they can review and iterate.
+
+After writing, report:
+- File path
+- Number of screenshot placeholders emitted (and a note that matching `.spec.ts` files were generated)
+- Any source files you couldn't find — the user may need to clarify