菜单
Standard for authoring and reviewing BigBlueBam per-app help.md files. Use whenever writing, structuring, or checking a help document for any app in the suite. Defines the canonical template, the User Story format, source priority, writing conventions, and the acceptance checklist.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | help-doc-authoring |
| description | Standard for authoring and reviewing BigBlueBam per-app help.md files. Use whenever writing, structuring, or checking a help document for any app in the suite. Defines the canonical template, the User Story format, source priority, writing conventions, and the acceptance checklist. |
One docs/apps/<app>/help.md per app, containing in order:
The full skeleton is reproduced at the end of this skill.
Code > existing docs/apps/ docs > marketing and screenshots > README. Document what the code does. If a doc or marketing claim is not backed by a route, component, or MCP tool, do not write it as fact; flag it.
Each story has: a Who, a Goal, a Before you start, numbered Steps that
name exact UI elements, a Result, and an optional Related. A new user must
be able to finish the story from its steps alone.
# <Display Name> - <One-line description of what it is>
> <One or two sentences: the job this app does and who reaches for it.>
## Overview
<2 to 4 short paragraphs: what the app is for, the problems it solves, and how
it fits with the rest of the suite. Name the core objects the user works with.>
### Key concepts
- **<Concept>** - <plain-language definition in the app's own vocabulary>
- ... (cover every term a new user must know: the nouns the app is built around,
the views, the states, the roles that matter)
### Where to find it
<The SPA path (for example /beacon/), how to reach it from the main nav, and any
prerequisites - permissions, an org, a project - needed before the app is usable.>
## Feature reference
<One subsection per user-facing feature. For each: what it does, where it lives
in the UI, and the explicit steps to use it. Group related features. Cover every
view, panel, action, and setting a user can touch.>
### <Feature name>
<What it is and when you would use it.>
To <do the thing>:
1. <step>
2. <step>
3. <expected result>
<Repeat for every feature.>
### Working with AI agents
<Short section: which of this app's actions agents commonly perform, the MCP
tools that drive them, and anything a human should know about reviewing or
approving agent work in this app. Point to docs/apps/<app> MCP-tools reference
for the full catalog.>
## User Stories
<The complete set of common use cases as named, step-by-step stories. See the
format in the User Story section above. Order them from most common /
onboarding-level to advanced.>
### Story: <short imperative title>
**Who:** <the role / persona doing this>
**Goal:** <the outcome they want, one sentence>
**Before you start:** <preconditions - permissions, existing objects, settings>
**Steps**
1. <Concrete action. Name the exact button / menu / field. Say where it is.>
2. <Next action, including anything the user must type or choose.>
3. <Continue until the goal is reached.>
4. <Final step.>
**Result:** <what the user sees and what state the system is now in.>
**Related:** <optional - features or other stories that extend this one, and any
MCP tool an agent would use to do the same thing.>
## Related
- Links to the other apps this one commonly hands off to or pulls from.
- Link to the app's MCP-tools reference and guide in docs/apps/<app>/.
Assemble or extend the printable, textbook-style BigBlueBam manual (the DOCX and PDF offered from /docs). Use when asked to build the downloadable manual, add or refresh a chapter, write chapter intros/callouts/quizzes, or change the book's design. Produces a bold, colorful, per-app book from the SAME content as the web docs, then converts to PDF.
Produce realistic, fully-populated screenshots of any view in the BigBlueBam suite from declarative YAML recipes — auth, content seeding, deterministic capture, and a manifest. Use when creating/updating docs or marketing-site assets, or refreshing captures after a UI change.
Triage, investigate, mitigate, and (after sign-off) resolve the open GitHub issues on eoffermann/BigBlueBam. Builds a dated issue_mitigations_<YYYYMMDD>.md dossier, posts an "investigating" acknowledgement on each issue, implements least-disruptive fixes on per-issue branches, has an independent agent re-verify each fix from the code alone, reports to Eddie, and on his go-ahead merges main→stable + closes addressed PRs. Use when asked to work through / cull / clear the repo's open issues. Pairs with the github-pr-cull companion skill for the unmerged-PR pass.
Triage the open/unmerged pull requests on eoffermann/BigBlueBam — assess each PR's approach against the code, then merge / revise / close with a documented rationale, under the same Eddie-sign-off gate as the issue cull. Invoked as the Phase 7 follow-up of github-issue-cull, or standalone when asked to clear out stale PRs. Records into the same dated dossier.
Standard for building and maintaining BigBlueBam's unified in-app help system: a "(?)" Help Center launched from every app's top bar (TOC, search, index, cross-references) sourced from docs/apps/<app>/help.md, plus right-click "Help: <element>" deep-links on UI elements that the help docs reference. Use when building, extending, or updating the help feature for any app.
Debug a UI feature by writing its expected-behavior user story, then walking the full stack top-down — UI control → handler → hook → API route → backend logic → data effect — and smoke-testing it live on the local dev stack with self-cleaning test data. Use when a UI element "does nothing", silently fails, or "looks wired but isn't", and before declaring ANY UI feature done. Nothing is "done" until the UI is proven to call real logic and that logic is proven to do what the story says.