--- name: ai-docs description: Use when the user says "AI-docs" / "put this in AI-docs", or explicitly asks to capture a structured deliverable — architecture, design, analysis, research, planning, or comparison results — as a persisted document. Writes a curated HTML doc into a docs directory (default AI-docs/, or any directory the user names) served by a local viewer. NOT for ordinary scratch/markdown file writes or quick notes unless the user asks for an AI-doc. user-invocable: true --- # AI-docs **Capture durable artifacts as curated HTML in a docs directory, viewed through a local server. Governs how output is represented, not what the task produces.** ## When to Use Activate this skill when the user wants something *captured* (not just discussed): - The user says **"AI-docs"**, "put this in AI-docs", "write a doc", "save/store this", "document this". - A plan, architecture decision, analysis, research finding, or comparison is *ready* to be recorded. - Any artifact that the user will re-read later and benefits from structure + a readable viewer. **`AI-docs` is the default trigger word and the default directory name.** It is not a fixed location: if the user names another directory (e.g. "put the security review in `security-docs/`"), write there instead. The same methodology serves any number of directories at once — different folders for different kinds of work, each viewable by pointing the engine at it. Treat the directory as a parameter, not a constant; the only hardcoded default (`AI-docs/`) lives in the engine, not in your behavior. ### When NOT to use - Exploration, questions, half-formed thoughts, quick clarifications → stay in chat. - The agent's reasoning, decisions, and back-and-forth → stay in chat. The user reads those there. - Don't pre-emptively dump intermediate notes into the docs directory. Capture when something is *ready*. ## Core principle This skill changes **representation, not substance.** The information the agent would produce for a task is unchanged — it is reorganized into a light structure, phrased tighter, and rendered as HTML so it is easy to consume long-term. Nothing is dropped: depth and exhaust move into a collapsible `Raw material` section, they are not deleted. See `./references/writing-style.md`. ## Workflow ### Step 1: Write the doc Pick the target directory (default `AI-docs/`, or whatever the user named) and create a `.html` file under it — `mkdir -p` the directory if it does not exist yet. There is nothing to scaffold: the engine lives in this skill and is pointed at the directory at run time. Create subfolders freely (the server walks the tree every request, so new files/folders appear on browser refresh). There is **no required directory layout**; organize by what makes sense for the work. Author a **body fragment only** (no ``/``/``/`