Miniapp Product Dev

Miniapp Product Dev

Use this skill for mini-program client engineering and platform delivery. It covers product-facing miniapp work across WeChat, Alipay, Douyin/TikTok, Baidu, and similar host platforms. It does not own general product strategy, backend service architecture, or visual design rules.

Framework Scope

Primary framework target: Taro (React-based multi-platform mini-program framework). Apply this skill's recipes assuming Taro unless the task states otherwise.

Adjacent frameworks recognized but not the default target:

• uni-app / Remax / kbone / mpvue: recipes here usually apply with framework-equivalent substitutions; verify before assuming behavior.
• Native WeChat / Alipay / Douyin / Baidu mini-program: host-platform contracts (config, capabilities, review, release) carry over; framework-specific code mechanics (JSX/hooks vs WXML/WXSS, lifecycle hooks, runtime APIs) require native-platform substitution.
• Embedded H5 inside a mini-program webview: this skill owns the mini-program shell, bridge contract, host capabilities, and review/release evidence; the H5 React/Vue page belongs to web-react-dev (or the relevant web skill).

If the team adopts a non-Taro framework as a new primary, the skill scope must be re-declared rather than letting Taro recipes silently apply to mismatched runtimes.

For evaluating whether Taro is the right choice for a given project (vs native, uni-app, Remax/kbone, or splitting per-platform), read references/framework-choice.md. Taro is the current default but not a permanent decision — re-evaluate when the project's target-platform set, design-system divergence, or maintenance signals change materially.

Maturity Baseline

The current rule set is vendor-spec + framework-canonical, not mature confirmed. It is grounded in: host-platform official guidelines (WeChat/Alipay/Douyin/Baidu), Taro official documentation and examples, and canonical Taro-ecosystem UI component libraries (taroify, NutUI-Taro, tdesign React mapping). It is not yet confirmed against a production-quality miniapp portfolio observed end-to-end. Treat positive rules as defaults to apply, anti-patterns as guardrails, and upgrade rules to confirmed only after they pass a real feature delivery without correction.

On existing team mini-program codebases: a team already running a Taro (or other) mini-program codebase does NOT automatically supply positive rules. Production use is evidence of distribution, not of quality. Until that codebase has been audited end-to-end against this skill's rules — or piloted through one real feature delivery cycle with retrospect captured via skill-extraction-workflow — it carries the quality-unverified label from references/source-evidence-map.md. Forward work uses this skill from the start; lessons from the existing code flow back through the extraction workflow, not by silently lifting patterns.

Runtime Compatibility

This skill is shared by OpenCode, Codex, and Claude Code. Keep instructions tool-agnostic: prefer repository-local scripts, platform developer tools, CLI commands, simulator evidence, screenshots, and explicit manual checks over host-specific features. When a tool is unavailable, record the missing evidence and use the closest deterministic check instead of pretending the platform was verified.

Routing

• Use product-rd-workflow first when the work spans product intent, design, service contracts, implementation, test, review, release, and follow-up.
• Use product-ui-ux-design before or alongside coding for visible page structure, interaction model, density, empty/error/loading states, trust copy, accessibility, and launch acceptance.
• Use ../product-ui-ux-design/references/multi-stack-strategy.md and ../product-ui-ux-design/references/multi-project-token-consistency.md when the mini-program is one of several client stacks under one brand (web desktop + H5 + native app + mini-program). Cross-end brand alignment (color tokens, typography, voice/tone, terminology, navigation labels, trust copy) is owned there, not here. This skill enforces the host-platform constraints on top of those tokens. For the scope of what must align across web + app + mini-program (beyond just theme and logo — including auth/onboarding copy, error vocabulary, payment confirmations, privacy disclosures, share/QR payload schema, deep-link routes), read references/cross-stack-alignment.md.
• Use web-react-dev for the React layer when Taro shares code with a React web project (see Sibling Boundary below).
• Use backend architecture/dev skills for API contracts, auth services, payment callbacks, subscriptions, persistence, async jobs, and admin/ops surfaces.
• For backend HTTP integrations, preserve current client wire behavior unless an explicit consumer-migration decision exists. Classify JSON vs protobuf-backed HTTP using ../platform-service-connectivity/references/protobuf-http-contract-signals.md.
• First decide whether the client diff touches the HTTP contract or wire behavior. Wire-unchanged page/component/state work does not need a backend owner round-trip and must not claim backend contract conformance.
• For unrelated client work, classify the diff with the canonical gate. If the surface is out of scope, client work may continue without claiming backend contract conformance.
• If the canonical gate classifies the diff as in scope, confirm the backend's recorded wire format or route back to the backend contract owner.
• Routine JSON/OpenAPI changes use the existing API contract record and do not require backend wire-format confirmation when the canonical reference classifies the surface as out of the protobuf wire-format gate.
• Mini-program request wrappers must consume the backend contract's recorded response envelope per ../platform-service-connectivity/references/http-response-envelope-contract.md: for surfaces on the canonical code/message/data envelope, page/component state reads typed business data from data; other shipped or non-JSON envelopes are consumed per their recorded contract. Read only fields present in the recorded contract — do not infer business fields from unrecorded top-level or fallback shapes — and scatter no duplicate envelope parsing across the client.
• If backend wire-format evidence is unreachable for an in-scope surface, stop at pending-contract-owner, name the backend owner or owning repo, record the attempted lookup, and set the next escalation path. An assumed-wire-format note never unblocks merge. The blocker clears only when a checkable owner record, quoted prior backend record, or explicit migration decision is available; if no owner responds within the team's review SLA, keep the client change blocked or downscope the touched wire-format surface and record the dropped surface as an open owner-routed gap. Do not claim backend contract conformance or completion for the removed slice.
• Do not fork IDL or hand-maintain duplicated DTOs in the mini-program repo.
• Use testing-strategy to choose unit, component, integration, miniprogram automation, E2E, manual device, and release verification layers.
• Use test-artifact-management when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.
• Use defect-diagnosis first for crashes, failed builds, platform review rejection, flaky device behavior, auth/payment/share failures, or production symptoms.
• Use feature-risk-router when the slice touches money, login/identity, user data, permissions, generated/AI content, write finality, platform review policy, or release risk.
• Use skill-extraction-workflow to feed learnings from real mini-program work back into this skill (or a sibling) — corrections, repeated defects, online-practice uptake, pilot retrospectives. New mini-program work runs through this skill from the start. Recorded extraction passes are necessary evidence for upgrading the maturity baseline, but the full upgrade-path criteria (real feature delivery cycle, host-platform review pass, cross-stack alignment confirmation, correction RCA per defect — see references/source-evidence-map.md → "Upgrade Path to mature confirmed") all apply; implementation hours alone do not move the baseline. Do not silently mine an older, quality-unverified team codebase for positive rules; route observations through the extraction workflow with the right evidence label (see references/source-evidence-map.md → "Team-owned mini-program portfolio").

Lifecycle and Neighboring Skills

How this skill sits inside the broader delivery loop for a mini-program feature. Each stage names its owning skill and what this skill receives from / hands off to it.

| Stage | Owner | What flows into this skill | What this skill hands back | |---|---|---|---| | Risk classification | feature-risk-router | Risk tags (money / identity / privacy / write finality / generated content / host capability), required gates | Confirmation that the gate set covers mini-program-specific risks (review policy, host capability, finality across host pay) | | Product / cross-stage delivery | product-rd-workflow | Product intent, scope, service contract, release plan | Mini-program-specific delivery considerations (multi-target shipping set, host review timeline, gray release lever choice) | | Design (visual, interaction, copy, states) | product-ui-ux-design | Design source (Figma), tokens, state enumeration, copy / voice, accessibility criteria; cross-stack alignment is owned in ../product-ui-ux-design/references/multi-stack-strategy.md + ../product-ui-ux-design/references/multi-project-token-consistency.md | Mini-program platform constraints on top of the design (safe-area, host gesture, capability denial states, host-native affordance), screenshot acceptance per shipped host | | Implementation — React layer + pure shared | web-react-dev | Component decomposition, hooks, state ownership, effect discipline, pure shared DTOs / validators / mapping | Mini-program contract on co-owned runtime adapters (auth epoch tuple, request cancellation, storage manifest, finality / idempotency, kill-switch, trace propagation) — enforced via the named co-owned-adapter owner + miniapp-contract tests (see "Sibling Boundary With web-react-dev" → shared-runtime-adapter row for the full gate) | | Implementation — mini-program runtime | This skill | Taro lifecycle, host APIs, platform branching, subpackage, capability adapters, multi-target build, review-safe copy | — | | Implementation — backend services | Go / Python service skills + llm-inference-integration | API contracts, server idempotency by (principal, tenant, action, business-key, fingerprint), payment reconciliation, share-token issuance, signed capability grants, server-side feature flags | This skill consumes those contracts. If the backend cannot supply a contract that a specific mini-program flow needs (server-business-key idempotency / bounded reconciliation / signed grants / fail-closed flag), route the block-or-downscope decision through feature-risk-router + product-rd-workflow with backend owner evidence — the legitimate exits are remove the risky capability, ship a read-only or non-finality subset, record a deferred-gate row with a tracking ticket, or block. Do not strand the work without an owner. | | Implementation — native / cross-platform app | app-cross-platform-dev | App-side equivalent surfaces (when the same product also ships native); used for cross-stack alignment cross-checks | — (mini-program is a separate host) | | Test strategy | testing-strategy | Layer choice (unit / component / API contract / mini-program automation / E2E / manual device / release smoke), scenario matrix | Mini-program-specific evidence requirements (one host compile is not multi-host pass; developer-tool compile is structural only; per-shipped-target real-device evidence is blocking) | | Debugging / production symptom | defect-diagnosis | Reproduction discipline, 5-Why root cause, regression closure | Mini-program-specific repro paths (developer tool, real device, host version matrix, share/scene param) | | Release / review submission / rollback | This skill (references/qa-release.md) | Per-host evidence matrix, server-flag kill-switch runbook, current platform-policy doc URL + date | — | | Post-ship learning capture | skill-extraction-workflow | RCA framing, source-evidence labels, dual-track review/challenge gates, sibling-skill mini-map | Updates to this skill's rules, Do Not list, references; upgrade-path progress toward mature confirmed; recurring anti-pattern entries |

Treat the loop as: risk-route → product/design → develop (this skill + web/backend) → test → release → debug → extract back. Skipping the extract-back step is how a team accumulates implementation hours without the skill ever maturing.

Repo-local agent contracts (AGENTS.md at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per product-rd-workflow's spec / repo-contract sync gate.

When checking a mini-program project against team standards, split conformance into deterministic and agent review evidence. Deterministic checks cover project config, target/platform build commands, subpackage config, generated API/IDL client usage, environment/lane config, TC traceability, CI gates, and required request/trace identifiers in central request wrappers. Agent review checks cover page/component boundaries, host capability contracts, shared adapter safety, finite-value mapping, multi-target release risk, and whether tests/device evidence cover the shipped targets. For the deterministic executor list (ecosystem ESLint/@typescript-eslint/dep-cruiser rules + tsconfig flags) and the mini-program-specific ESLint config that enforces the two host-boundary invariants — no-restricted-imports banning react-dom/react-dom/* (the logic layer has no DOM), and a no-restricted-syntax selector confining process.env.TARO_ENV branching to the adapter/platform layer (use ESLint, which runs on the AST, not a regex source-scan) — see testing-strategy/references/fitness-functions.md §4.1.3 (client language-basics; spec 006).

Sibling Boundary With web-react-dev

Taro is React syntax compiled to mini-program runtime; a Taro project typically shares a substantial portion of code with a React web project in the same monorepo. Without an explicit boundary, ownership of state hooks, API clients, and shared components drifts.

| Layer | Owner | Notes | | --- | --- | --- | | React component structure, hooks, JSX, TSX types | web-react-dev | Component decomposition, state lifting, effect discipline are the same rules. | | Pure shared layer (DTOs, types, validators, pure mapping) | web-react-dev (monorepo pkg-shared) | No platform branches; no I/O. | | Shared runtime adapters consumed by mini-program targets (request client, auth state machine, storage namespace, finality/idempotency wrapper, observability transport) | Co-owned with a named final-decision owner (one engineer per adapter, recorded in repo). web-react-dev sets browser semantics; this skill's contract — full session-epoch tuple fencing, request cancellation across route switch, storage namespacing + manifest + historical-prefix purge, sensitive-field handling, late-callback fencing, server-business-key idempotency, pending-reconciliation with bounded timeout on cold start / page-show / re-login, support-id propagation, kill-switch dimensions, trace propagation — is a blocking acceptance gate before mini-program targets import the adapter. Web may not merge an adapter change that is browser-safe but mini-progr

…

Source & license

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

• Author: ccoalm
• Source: ccoalm/ccl-skills
• License: Apache-2.0

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