sop-builder

SOP Generator

This skill creates properly formatted IT Standard Operating Procedure (.docx) documents that match a specific template structure.

SOP Structure

Every generated SOP must have exactly these sections in this order:

1. Title — The process name (e.g. "How to Reset a User's MFA Device")
2. Purpose — 1–5 sentences: why this matters and what goes wrong if skipped. Bullets welcome.
3. Procedure
   • Inputs — Bullet list of prerequisites (software, permissions, credentials, tools, context)
   • Steps (1–8 max) — Each step has:
     • A mini-result headline: short observable result phrase (e.g. "User account located in Active Directory")
     • A body: how to achieve it (text and emojis only — no images or tables)
4. Outputs — What confirms the procedure was completed correctly (observable end results)
5. FAQs — Always required. One or more Q&A pairs.

Step 1: Gather Content

Accept input in any form — pasted outline, plain language description, or answers to questions.

Map what the user provides to the five sections above. Then ask only about what's missing:

• If Title is unclear → ask for the exact process name
• If Purpose is missing → ask: "Why does this process matter? What breaks if it's skipped?"
• If Inputs are missing → ask: "What does someone need before starting — any tools, access, or info?"
• If Steps are vague → ask for the steps one at a time: "What's step 1, and what's the visible result when it's done?"
• For each step, extract any navigation path (e.g. Settings > People > Invite) and put it in nav. Do not repeat the navigation path in body text as well.
• For each step, ask if the user wants to include a screenshot: "Do you have a screenshot for this step? If so, drop the file path." Accept text-only, image-only, or both — user decides per step.
• If Outputs are missing → ask: "How do you know when this is fully done and correct?"
• If FAQs are missing → ask: "Are there common questions or edge cases that come up with this process?"

Never invent placeholder content. Only write what the user provides or confirms.

Write lean. Every word must earn its place. No filler phrases ("Please note that...", "It is important to..."), no restating the headline in the body, no over-explaining obvious clicks. If a nav breadcrumb covers where to go, the body should only cover what to watch for or why — not repeat the path in sentence form.

Write for non-technical readers. SOPs are sent to clients who may have no technical background. Apply these rules throughout:

• Step headlines speak directly to the reader: "You are logged in" not "Login completed"
• Use "website name" not "domain name", "ending" not "extension", "tick" not "select permission"
• Describe UI elements by what the reader sees: "three-line menu icon", "green Available label"
• FAQs should read like a calm answer to a confused client, not a tech support article

Stay strictly on scope. An SOP covers exactly one process — no more. Do not pad steps with adjacent actions that belong to a separate SOP (e.g. adding users, assigning roles, connecting additional assets). If a logical next step falls outside the scope of this SOP, note it in Outputs as "→ See [related SOP name] to continue" rather than including it as a step here.

If the Purpose section cannot be meaningfully written (process too vague), flag this to the user before continuing.

Step 2: Confirm Before Generating

Once all sections are gathered, show a brief structured summary for the user to confirm:

Title: [title]
Purpose: [first sentence...]
Inputs: [count] items
Steps: [count] steps
Outputs: [first output...]
FAQs: [count] Q&A pairs

Ready to generate the .docx?

Only proceed to generation after confirmation (or if the user says "yes" / "go ahead" / similar).

Step 3: Generate the .docx

Build a JSON object with the SOP content and pass it to the generation script.

Run the script

NODE_PATH="${CLAUDE_PLUGIN_DATA}/node_modules" node "${CLAUDE_PLUGIN_ROOT}/scripts/generate_sop.js" '<JSON_STRING>'

Where <JSON_STRING> is a single-quoted JSON string with this structure:

{
  "title": "How to Reset a User's MFA Device",
  "purpose": ["Sentence one.", "Sentence two if needed."],
  "inputs": ["Admin access to Azure AD", "User's employee ID or email address"],
  "steps": [
    {
      "headline": "User account located in Azure AD",
      "body": "Navigate to portal.azure.com → Azure Active Directory → Users. Search by name or email.",
      "image": "C:\\Users\\23057\\Downloads\\step1_screenshot.png"
    },
    {
      "headline": "MFA reset button clicked",
      "image": "C:\\Users\\23057\\Downloads\\step2_screenshot.png"
    },
    {
      "headline": "Confirmation email sent to user",
      "body": "The user will receive a reset prompt on next login. ✅ Confirm before closing the ticket."
    }
  ],
  "outputs": ["User receives a new MFA setup prompt on next login", "✅ Ticket marked resolved"],
  "faqs": [
    {
      "question": "What if the user doesn't receive the MFA prompt?",
      "answer": "Check that the MFA reset was saved and not just previewed. Re-open the user record to confirm."
    }
  ]
}

Image rules

• body and image are both optional per step — but every step needs at least one
• When both are provided: short text appears first, image appears below it
• When only image: the screenshot carries the step on its own
• When only body: text-only, same as before
• Supported formats: PNG, JPG/JPEG
• Images auto-scale to fit page width — no need to resize beforehand
• Use absolute Windows paths with double backslashes (C:\\Users\\...)
• If an image path is not found at generation time, it is skipped with a warning — the rest of the document still generates

### Filename

Derive the filename from the title: lowercase, replace spaces with underscores, append `_sop.docx`.
Example: "How to Reset a User's MFA Device" → `how_to_reset_a_users_mfa_device_sop.docx`

The script saves the file to the **current working directory** automatically.

### After generation

1. **Ask the user which format they want:**
   > "Your SOP is ready. Would you like it as a **Word doc (.docx)**, a **PDF**, or **both**?"

2. If PDF is requested, convert using Word's COM object via PowerShell — same filename, same folder, `.pdf` extension. Use the full path returned by the script (current working directory):
```powershell
powershell -command "
\$word = New-Object -ComObject Word.Application
\$word.Visible = \$false
\$doc = \$word.Documents.Open('<full_path_to_docx>')
\$doc.SaveAs([ref]'<full_path_to_pdf>', [ref]17)
\$doc.Close()
\$word.Quit()
"

3. Open the file automatically once ready:

start "" "<full_path_to_file>"

(Use the correct extension based on what the user chose.)

4. Tell the user the file is open and ask if anything needs adjusting.

Emoji usage guidance

Use emojis sparingly and purposefully — not decoratively:

• ➡️ for tips, notes, or "look for this" callouts within step bodies
• ⚠️ for warnings or things that can go wrong
• ✅ for confirmed-done outputs
• Avoid emojis in the Title, section headers, or FAQ questions