docs(readme): add user prompt examples + contact section#86
Merged
Conversation
Two README gaps closed:
1. **User-facing example prompts.** The README had exactly one example
("Walk me through the OAuth flow in this codebase"), so users had
nothing to anchor on for what to *ask* their agent. Expanded into 8
concrete prompts covering common shapes: auth flows, request paths,
pipelines, click-to-action traces, middleware, cache, state machines,
tooling lifecycles. Matches the trigger-phrase template in
17-install-and-activation-flow.md:344-353.
2. **Contact channel** (closes audit W11). Added a Contact section
right above License with both a GitHub-issue funnel and the
openhop.dev@gmail.com inbox. The issue link is the primary funnel
(public, searchable); the email is the backup for things that
shouldn't be a public issue.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
WalkthroughThe README is updated to include expanded example prompts for generating OpenHop YAML flows and a new "Contact" section. The usage example block is replaced with multiple specific diagramming questions and a description of the ChangesREADME Documentation Updates
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
naorsabag
added a commit
that referenced
this pull request
May 8, 2026
…thorship (#87) * docs(readme): split prompts into a dedicated Use cases section + fix Why-prose authorship Two README polish changes: 1. **Why section authorship.** Previous prose said "You describe the flow in YAML (your agent writes it for you)" — contradictory. Users don't write YAML; they describe the codebase area in English and the agent writes the YAML. Rewrote as: "You ask in plain English; your agent writes the flow as YAML and pushes it; OpenHop renders…" 2. **Move prompts to a dedicated `## Use cases` section.** The 8 example prompts added in #86 were inline inside "Give your agent the skill" alongside install instructions, which mixed two concerns: setup-once vs use-every-day. Split them: the install section keeps the install steps and a one-line pointer; the new Use cases section is a discoverable section users can deep-link to (anchor added to the top-of-README nav). Also added a one-line trigger-shape note ("explain / walk through / trace / visualize / diagram _ flow") at the bottom of Use cases — it's the same activation phrase pattern documented in 17-install-and-activation-flow.md, surfaced for users who want to know what the skill actually matches on. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): restructure Install into 3 explicit paths (kicking-tires / agent-driven / contributor) Previous Install table mixed two orthogonal axes — server-side commands (demo, serve) and agent-side commands (init, openskills) — listed as peers, which made it look like the user picks one. Reality: most users need *both* a server (so flows render) and a skill (so the agent knows how to call openhop). Restructured into three labeled paths: - Path A: just see what it does → `npx openhop demo`. One command. - Path B: real agent-driven use → 3 explicit steps: 1. install the skill (init or openskills) 2. run the server long-lived (`npx openhop serve`) 3. ask the agent for a flow - Path C: contributor → clone, npm install, npm run dev. Also dropped the now-redundant "## Give your agent the skill" section (its content is folded into Path B). Updated nav anchor from "AI skill" → "Install" since the install section now covers skill setup explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): lead with the skill — that's the install. Demote demo to a preview. Previous Install section listed Path A (kicking the tires via demo) and Path B (agent-driven, multi-step) as peers. That framing was wrong: OpenHop has no use without an AI agent. The product is the skill; the CLI just paints the pixels. Restructured to put the skill install front-and-center: - Path A (Tier-1, auto-detect): `npx openhop init` - Path B (Tier-2, via OpenSkills): `npx openskills install …` Both paths are about HOW to install the skill (the only required step). After install, the agent boots `openhop serve` automatically when it needs to render — the user doesn't run a server unless they want to. `openhop serve` and `openhop demo` are now positioned as optional / preview commands beneath the skill install paths, with explicit framing: serve = "if you'd rather pre-start it yourself", demo = "just looking, no agent involved." That matches how a first-time user actually consumes the README. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): drop italics from Use cases prompt bullets Each prompt was wrapped in _underscores_ for italics, which renders visibly slanted on GitHub and reads as noisy formatting on a straightforward bulleted list. Plain-quoted strings carry the "agent prompt" signal on their own. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): drop the descriptive text under each install path Each path now shows just the command. Section headers carry the context (which clients each path is for) and the commands speak for themselves. Removes ~5 paragraphs of "what this does" prose that was restating what the section header already said. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): broaden the activation pattern line to match the examples CodeRabbit (PR #87 review) caught a mismatch between the pattern description and the example prompts above it. The previous text suggested every prompt must use one of five verbs *and* include the word "flow" — but several listed examples (state machines, "Show me how the checkout pipeline processes…", "How does cache invalidation work?", etc.) don't fit that strict shape. Rewrote the pattern line to describe the broader activation surface the examples actually demonstrate: prompts asking the agent to explain / walk through / trace / visualize / diagram how something works in code — flows, request paths, lifecycles, state machines, processing pipelines, click-to-action traces. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): align activation pattern with the skill's authoritative trigger list Per review: the README's activation pattern should match the skill's own declared triggers. Updated to mirror SKILL.md:3 frontmatter verbatim: Verbs (6): understand, explain, walk through, trace, visualize, diagram Subjects: data, requests, control, auth, or state flows through code Previous README had only 5 verbs (missing "understand") and described the subjects as a vaguer list ("flows, paths, lifecycles, state machines, ..."). The skill router phrase-matches on the SKILL.md frontmatter, so the README description should be identical to maximise the chance that what users see in the README is what actually activates the skill. Also added a pointer to the full per-phrase trigger list in skills/openhop/SKILL.md (lines 19-30) for users who want to dig in. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(readme): drop "understand" from the activation verb list Per request. The README now lists 5 verbs (explain, walk through, trace, visualize, diagram) where the skill's frontmatter has 6 (includes "understand"). The skill router still phrase-matches "understand" — so user prompts using that verb still activate the skill — the README just describes the more concrete subset. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two small README additions that close real gaps:
1. User-facing example prompts (8 of them)
Before today the README had one example prompt — `"Walk me through the OAuth flow in this codebase."` That left users with nothing to anchor on for what to actually ask their agent.
Replaced the single line with a list of 8 concrete prompt shapes:
These cover the common phrase patterns the skill's frontmatter `description:` already advertises (per `17-install-and-activation-flow.md:344-353`), so users have direct examples to copy-paste against their own codebase.
2. Contact section (closes W11)
Added a `## Contact` section right above `## License` with two channels:
Closes the README "no contact email" gap from `READINESS-AUDIT.md` §W11 and `18-zero-cost-stack.md:257`.
Diff
Testing
Checklist
🤖 Generated with Claude Code
Summary by CodeRabbit
openhop pushand receiving URL responses