# Docs Frontend

> Generate human-readable, styled user documentation by driving the running app with Playwright MCP, taking real screenshots per role, and writing the guide to the Obsidian vault. Use when frontend views/flows changed.

- **Type:** Skill
- **Install:** `agentstack add skill-gunesbizim-agent-smith-docs-frontend`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gunesbizim](https://agentstack.voostack.com/s/gunesbizim)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gunesbizim](https://github.com/gunesbizim)
- **Source:** https://github.com/gunesbizim/agent-smith/tree/main/templates/skills/docs-frontend

## Install

```sh
agentstack add skill-gunesbizim-agent-smith-docs-frontend
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

You are a senior technical writer. Produce **human-readable, styled user documentation** — "how to use the system" — for the target given in `$ARGUMENTS` (a view, flow, or `latest` for the branch diff). The audience is end users, not developers.

**This skill documents by SHOWING:** every documented flow is driven live in the browser via Playwright MCP and illustrated with real screenshots per role.

## How this runs (LLM + write path)

- **LLM engine:** this skill runs inside the Claude Code session — the Claude Code CLI *is* the LLM. There is no `--llm` flag, no API key, and no external model to configure; generation is on by default whenever you run the skill. The optional `/advisor` step only swaps the *planning* model when one is configured.
- **Write path:** the guide is written to the project's Obsidian vault through the **`obsidian` MCP** by default, falling back to `docs/user-guide/` in the repo if that MCP is not connected (see Step 4). Screenshots always land in the gitignored `.playwright-mcp/` directory.
- **Stack-agnostic:** routes, dev-server command, and directories come from this project's detected stack via `{{...}}` variables — nothing here is tied to a specific framework.

## Available MCP tools

These MCP servers are configured for this project — use the ones relevant to the step:

- **gitnexus** — code graph: impact, callers, route maps, blast radius before/after changes.
- **git-memory** — why code changed: commit history, bug-fix history, file timelines.
- **playwright** — drive the running app to capture real per-role screenshots.
- **chrome-devtools** — deep inspection (console, network) when a flow misbehaves.
- **obsidian** — write the styled user guide into the configured Obsidian vault.

Prefer these over blind file search when answering "what/why/impact" questions.
See `docs/architecture/mcp-tools.md` for exact tool names and signatures.

---

## Step 0 — Plan first (mandatory)

**Before navigating anywhere**, use Claude Code's built-in `/advisor` (a stronger planning model; falls back to the current session model if no advisor is configured) to produce a scoped documentation plan. Pass:
- The target (`$ARGUMENTS` or changed views from `git diff origin/main...HEAD --stat -- {{FRONTEND_DIR}}/`)
- Which roles see the flow differently
- Existing guide sections in Obsidian that need updating vs creating

---

## Step 1 — Identify what changed (incremental mode)

```
git diff origin/main...HEAD --name-only -- {{FRONTEND_DIR}}/views {{FRONTEND_DIR}}/components
mcp__gitnexus__detect_changes()        # map diff to affected flows
mcp__gitnexus__query("ChangedView")    # which user flows pass through the changed view?
```

Document only flows touched by the diff (unless `$ARGUMENTS = all` → full system guide).

---

## Step 2 — Prepare the running app

1. Dev server must be running: `cd {{FRONTEND_DIR}} && {{FRONTEND_DEV_SERVER_CMD}}` (ask the user to start it if not).
2. Backend running with dev auth so roles can be switched.
3. If either is unavailable, **say so and stop** — never fabricate screenshots or describe UI from code alone.

---

## Step 3 — Drive the app and capture (Playwright MCP)

For **each role** whose experience differs in the documented flow:

```
mcp__playwright__browser_navigate("http://localhost:3000/")
mcp__playwright__browser_resize(1440, 900)
mcp__playwright__browser_snapshot()              # a11y tree — find elements to interact with
mcp__playwright__browser_click / browser_type / browser_fill_form   # walk the real flow
mcp__playwright__browser_take_screenshot(filename="--.png")
mcp__playwright__browser_wait_for(...)           # wait for async states (job polling, toasts)
```

**Capture rules:**
- Screenshot every meaningful step: entry screen → filled form → confirmation → result.
- Capture role differences explicitly.
- Capture state variants: empty list, loading, success toast, error banner.
- Name files `--.png` — stable, re-runnable names. The playwright MCP is configured with `--output-dir .playwright-mcp`, so files land in the gitignored `.playwright-mcp/` directory (never committed). Reference them as `.playwright-mcp/--.png` when embedding.

**Console check:** `mcp__playwright__browser_console_messages` after each flow — flag errors as a smoke test but continue documenting.

**When a flow misbehaves** (blank screen, unexpected error state, slow load), switch to chrome-devtools for deeper inspection before writing the docs step:

```
mcp__chrome-devtools__list_console_messages()      # capture JS errors and warnings in the flow
mcp__chrome-devtools__list_network_requests()      # identify failed or slow API calls
mcp__chrome-devtools__performance_start_trace()    # start a performance trace
# reproduce the misbehaving action
mcp__chrome-devtools__performance_stop_trace()     # stop and capture the trace
mcp__chrome-devtools__performance_analyze_insight() # surface rendering bottlenecks or long tasks
```

Document findings inline in the guide under a "Known issues" callout or "Things to know" bullet so users understand what they may encounter. Fix broken flows with the dev team before publishing if the error is blocking.

---

## Step 4 — Write the guide (Obsidian MCP)

Write the guide to the Obsidian vault:

- Path: `/docs/user-guide/.md` (one note per flow; update existing notes in place).
- Embed captured screenshots.
- If Obsidian MCP is not connected, write to `docs/user-guide/.md` in the repo instead.

### Guide structure — per flow

```markdown
# 

> Who can do this: 

## What this is for
2–3 sentences, plain language, no jargon.

## Step by step
1. **Open** ... (screenshot)
2. **Fill** ... (screenshot)
3. **Click** ... what happens next
4. **Result** ... (screenshot)

## Differences by role
| | Role A | Role B | Role C |
|---|---|---|---|
|  | ✓ | ✓ | ✗ shows disabled button with tooltip |

## Things to know
- What error messages mean and what to do about them.
```

### Style rules

- Plain language. Write for end users, not developers — no HTTP verbs, no component names, no status codes.
- UI labels quoted as they appear on screen, with explanation.
- Every step has a screenshot — a step without one is a TODO, not done.
- Role differences always explicit — never "some users may not see this".
- Async behavior explained in human terms.

---

## Recommended best practices (suggestions — not blockers)

From `docs/architecture/best-practices.md` (Documentation → Recommended), surface adoptable
guide standards — e.g. document accessibility affordances, keep one note per flow updated in
place, link related flows. Offer these as suggestions; never block the guide on them.

## Step 5 — Verify

- [ ] Every documented step was actually performed in the browser this session.
- [ ] Every screenshot file exists and is referenced in the guide.
- [ ] All roles checked (or the guide states which roles the flow applies to).
- [ ] Guide written to Obsidian vault (or repo fallback, explicitly noted).

---

## Output format

1. List flows documented + roles covered per flow.
2. List screenshot files captured.
3. Obsidian note paths written (or repo fallback paths).
4. Console errors encountered during walkthroughs (flagged for the team).
5. Flows that could NOT be documented (server down, role unavailable, feature behind 501).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gunesbizim](https://github.com/gunesbizim)
- **Source:** [gunesbizim/agent-smith](https://github.com/gunesbizim/agent-smith)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gunesbizim-agent-smith-docs-frontend
- Seller: https://agentstack.voostack.com/s/gunesbizim
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.