ballerina-platform/ballerina-library/generate-connector-docs

Generate Connector Docs

Create the integration and documentation directly in the current agent. Never start a nested agent, publish artifacts, or run git commands. The one exception is the connector-doc-generator step below, which itself calls the claude CLI — treat that as a separate, already-reviewed tool the user explicitly opts into, not something this skill's own scripts do.

Inputs

Require only a full Central coordinate:

• organization/package
• organization/package:version

Reject a bare package name. Treat an omitted version as latest. Accept optional user guidance for operation, authentication, or category choices; it overrides the workflow's default selection heuristics. Everything else — category, GitHub repo name, and the docs-integrator/connector-doc-generator/integration-samples locations — is resolved automatically per Steps 2–4 and 13 below; only fall back to asking the user when auto-resolution genuinely can't find an answer.

Run the workflow

1. Verify that the bundled playwright MCP server's browser_* tools are available. If they are unavailable, stop before creating artifacts. Tell the user to inspect /mcp and run /reload-plugins; do not run claude mcp add or modify personal Claude settings.
2. Resolve the requested coordinate and run python3 "${CLAUDE_SKILL_DIR}/scripts/prepare_run.py" "ORGANIZATION/PACKAGE[:VERSION]" --root "${CLAUDE_PROJECT_DIR}" --docs-repo-root DOCS_REPO_ROOT, where DOCS_REPO_ROOT is resolved as follows, in order, before this call: an explicit path the user already gave in this conversation; a docs-integrator directory the agent already knows about from earlier context; a sibling of ${CLAUDE_PROJECT_DIR}'s parent named docs-integrator; otherwise ask once with the "2+1" pattern (most likely candidate, a second plausible one, or a custom path). If no docs-integrator checkout exists or the user wants a scratch-only preview, omit --docs-repo-root entirely — the workflow then behaves exactly as a local preview: everything stays under artifacts/<organization>-<package>/ in ${CLAUDE_PROJECT_DIR} and nothing is written outside it. prepare_run.py auto-derives the catalog category from the resolved package's own Central metadata (its Area/... keyword) and the GitHub repo name (module-<organization>-<package>, using the coordinate's own organization) — pass --category or --github-repo explicitly only to override a wrong or missing derivation. Stop on invalid input, missing Central metadata, or an existing completed or nonempty output directory.
3. Read the emitted context JSON. Use its absolute run_dir, sample_dir, screenshots_dir, and doc_path values throughout the run. When a docs-integrator target was resolved, also note category_slug, module_slug, docs_connector_dir, docs_overview_path, and github_repo for later steps. If category_slug came back empty (the package has no Area/... keyword), ask the user for one of connector-doc-generator's fixed slugs (ai-ml, built-in, cloud-infrastructure, communication, crm-sales, database, developer-tools, ecommerce, erp-business, finance-accounting, healthcare, hrms, marketing-social, messaging, productivity-collaboration, security-identity, storage-file) and re-run Step 2 with --category before continuing.
4. Generate the sibling connector pages. When a docs-integrator target was resolved, locate a local connector-doc-generator checkout the same way as Step 2 (already known from context, a sibling of DOCS_REPO_ROOT's parent, or ask once) and offer to run it before continuing — unless docs_overview_path already exists, in which case connector-doc-generator has already run for this connector and this step can be skipped. State plainly that it calls the claude CLI directly (real Anthropic API cost, roughly $0.50–$1.00 for a single-client connector per its own README, a few minutes of runtime) and wait for explicit confirmation — do not run it silently. On confirmation, from the connector-doc-generator directory:

``shell bal run -- -CgithubRepo=<github_repo> -Ccategory=<category_slug> -CdocsRepoRoot=<DOCS_REPO_ROOT> ` This writes overview.md, an applicable setup-guide.md, and action-reference.md (and trigger-reference.md if the connector has a listener) into docs_connector_dir, and patches sidebars.ts and the catalog index.mdx with the connector's own entry. **Publishing the example page in Step 12 requires overview.md to exist** — if the user declines this step and no overview.md is already present, skip Step 12 too and report the example as scratch-only; do not invent a standalone sidebar entry for it. Read the generated pages afterward and fix two known mechanical rough edges by hand before moving on: the display name connector-doc-generator derives from the module slug is naive title-casing (e.g. "Hubspot" instead of "HubSpot") — correct it in overview.md's frontmatter title, and in sidebars.ts/index.mdx's new entries, to match the connector's real brand capitalization; and its prompt templates sometimes still slip the raw Ballerina package identifier ({{org}}/{{package}}) into prose sentences in overview.md or action-reference.md — reword any such sentence to name the connector instead, the same rule already applied to this skill's own example-page template and to generating-connectors' README templates. Leave the identifier alone inside code blocks, import statements, and the GitHub repository link, and leave the frontmatter description field alone — every sibling connector's description` already includes its raw package identifier by established site convention.

1. Check node, npx, python3, Pillow (python3 -c "import PIL"), code-server, and the wso2.wso2-integrator code-server extension (code-server --list-extensions). Ask before installing a missing prerequisite or downloading Chromium. Install Pillow only from ${CLAUDE_SKILL_DIR}/scripts/requirements.txt. Do not install silently.
2. Reuse a healthy code-server on a user-specified port or port 8080 when the user provides its access credentials; retain those credentials as CODE_SERVER_CREDENTIAL only in the current agent's context and use them to authenticate the browser session. Otherwise generate a per-run CODE_SERVER_TOKEN with python3 -c 'import secrets; print(secrets.token_urlsafe(32))', keep it only in the current agent's context, and start PASSWORD="$CODE_SERVER_TOKEN" code-server --auth password --bind-addr 127.0.0.1:PORT SAMPLE_PARENT; use that token to authenticate the browser session. Redirect output from a run-started server to run-log/code-server.log and record its PID. Never copy either credential into artifacts, logs, screenshots, or the final report. Stop only a server started by this run, then discard the applicable credential.
3. Read the connector UI workflow completely before browser interaction. Complete its clean-workspace gate before connector work: close the global Chat/Copilot secondary sidebar, integrated terminal, Welcome tab, unrelated editor/source tabs, and transient popups while keeping the WSO2 Integrator visual editor and left project-tree primary sidebar open. Treat that project sidebar as a blocking invariant through all six screenshots. Do not capture screenshot 01 until a fresh snapshot verifies the clean frame. Follow the reference through all six milestones. Use the bundled playwright MCP tools. Limit DOM evaluation to the reference's narrowly scoped scrolling and nested-canvas procedures; do not run arbitrary or page-wide browser code.
4. After every browser_take_screenshot call, immediately run python3 "${CLAUDE_SKILL_DIR}/scripts/collect_screenshot.py" RETURNED_PATH SCREENSHOTS_DIR/FILENAME. Keep filenames sequential from 01 through 06.
5. Create the integration using the context's exact sample_name at sample_dir. Make sample_dir the project root: Ballerina.toml and the generated .bal files must live directly within it. Do not rename the directory or add a suffix. If the UI creates the project elsewhere or one level deeper, copy its contents into sample_dir before finalization.
6. Read the documentation contract and Microsoft writing style completely before writing. Copy ${CLAUDE_SKILL_DIR}/assets/templates/connector-example-doc.md to doc_path, then replace every placeholder with facts from the completed workflow. Remove template comments and inapplicable conditional sections. Always author with the ../screenshots/... relative image links from the template — never hand-write the docs-integrator site's absolute /img/... form; that rewrite happens mechanically in Step 12. Do not author from a blank file, create an intermediate execution prompt, or use a second model for enforcement.
7. Run python3 "${CLAUDE_SKILL_DIR}/scripts/finalize_run.py" --context CONTEXT_PATH. It deterministically injects Try it yourself, calls append_central_examples.py to append examples from the cached Central API response, and validates the output. If it reports failures, correct the guide or artifacts and rerun until it succeeds.
8. When a docs-integrator target was resolved and `docs_overview_path` exists (connector-doc-generator has already produced overview.md, whether just now in Step 4 or in an earlier run), publish the example page through connector-doc-generator's own shared integration scripts rather than reimplementing that logic in this skill:

``shell python3 <connector-doc-generator>/scripts/integrate_example.py \ --docs-repo DOCS_REPO_ROOT --artifacts-dir RUN_DIR \ --category CATEGORY_SLUG --module MODULE_SLUG --mode connector python3 <connector-doc-generator>/scripts/validate_docs.py \ --docs-repo DOCS_REPO_ROOT --category CATEGORY_SLUG --module MODULE_SLUG \ --reference --examples ` integrate_example.py reads the single guide under RUN_DIR/workflow-docs/ and the six PNGs under RUN_DIR/screenshots/ (exactly run_dir, doc_path, and screenshots_dir from context.json), rewrites the guide's ../screenshots/... links to the site's absolute /img/connectors/catalog/<category>/<module>/... form, copies the screenshots into the static image tree, writes the guide to docs_connector_dir/example.md (adding a title: "<Name> Example" frontmatter block first, since the guide's own template is deliberately site-agnostic and never writes one itself), reconciles sidebars.ts so the connector's existing category block lists the example page, and adds an Example bullet to overview.md's Documentation section if one isn't already there — it fails loudly if overview.md is missing, by design, so do not attempt this step without it. Every generated page's title follows WSO2's own <Connector Name> <Section> convention (Title Case, confirmed against mi.docs.wso2.com and docs-integrator's pre-existing Twilio/HTTP pages) — overview.md/setup-guide.md/action-reference.md/trigger-reference.md get this from connector-doc-generator's templates directly; only example.md's title is this skill's own responsibility, via integrate_example.py as just described. validate_docs.py then re-confirms the whole page set and sidebar are internally consistent, but it has no trigger-aware check: if Step 4 generated trigger-reference.md (the connector has a listener), separately confirm that file still exists and is non-empty in docs_connector_dir before reporting success — a missing or emptied trigger reference can otherwise pass validate_docs.py` silently. If either script fails, fix the reported issue and rerun rather than hand-patching docs-integrator files directly. Leave every docs-integrator change as an uncommitted working-tree edit — never commit, push, or open a pull request against it.

1. **Offer