| name | sample-app-design |
| description | Spec a sample app or SDK quickstart that demonstrates the real value path as production-grade, runnable code — it runs from a clean checkout, handles errors, pins versions, and has no hardcoded secrets. Use when designing or reviewing sample code that developers will copy verbatim. |
Skill: Sample-app design
Design sample code that a developer can copy into production without learning a bad
habit. Sample code is production code — it's copied verbatim into real codebases.
When to use
- You need a sample app or SDK quickstart to show off the product's value path.
- A snippet/sample is about to be published and needs a production-grade review.
- A toy example is setting developers up for a cliff when they hit the hard parts.
Procedure
- Pick the value path, not a toy. The sample demonstrates the real reason a
developer would use the product — including the parts that are genuinely hard.
Hiding the hard parts is a future support ticket.
- Scope it to runnable. It compiles and runs from a clean checkout with a
documented, minimal setup. If it doesn't run from clean, it isn't done.
- Handle errors. Show the real failure modes (rate limits, auth expiry, bad
input) and the correct handling — not a happy-path-only snippet that breaks the
moment reality intrudes.
- Secure by default. No hardcoded secrets — env vars or a secret manager,
never a literal key. Teach the secure pattern, because everyone who copies it
inherits it. Route auth/secret deep dives to
security-engineering.
- Pin versions so the sample doesn't rot when a dependency ships a breaking
change.
- Mark any product friction for
developer-advocate to file — don't bury it in
prose. Capture the spec in the
sample-app-spec template.
Output
A sample-app spec (value path, runnable scope, error handling, secure patterns,
pinned versions) ready for the content-engineer to build.
Anti-patterns (the hook flags these)
- A sample with a hardcoded secret/API key (teaches a vulnerability at scale).
- A sample that swallows errors (empty catch / ignored failure).
- A toy that hides the hard parts and sets up a cliff.
