Use when Codex needs to turn an empty or partial HarmonyOS/OpenHarmony project into a complete working application or demo-ready sample. Covers official Stage-model project setup, directory layout, DevEco configuration, ArkTS UI architecture, state-management choices, test expectations for complete or validation-oriented apps, ability and native integration boundaries, and staged verification. Trigger on requests to build a HarmonyOS app from scratch, scaffold a project, complete an unfinished app, create a sample app, set up DevEco or hvigor structure, add abilities or native integration, or define a project architecture and delivery plan.
Build HarmonyOS projects in phases. Do not jump straight into feature code from an empty repository. Establish the official Stage-model project shape, configuration, runtime boundaries, and verification flow first, then implement features incrementally.
Use official HarmonyOS docs and official samples before inventing structure. Prefer local copies discovered through HARMONYOS_DOCS_ROOT and HARMONYOS_SAMPLES_ROOT. If docs are unavailable locally, fall back to searching the official HarmonyOS documentation site at https://developer.huawei.com/consumer/cn/doc/.
Read references/project-blueprint.md for the official build-first project shape, references/project-init-checklist.md when the user's request is underspecified and you need the minimum delivery contract, references/system-client-pattern.md for optional layering patterns that appear in official MVVM or system-capability samples, and for staged completion criteria.
For official SDK toolchain details such as hdc, bm, aa, packaging, signing, and device-side deploy flows, use $harmonyos-sdk-build-deploy. This skill should decide when build and deploy verification is required, not restate the full command-line tool reference.
For unit, UI, or ohosTest expectations in complete or validation-oriented app work, use $harmonyos-test-kit.
For page structure, navigation model, responsive or adaptive layout, multimodal interaction expectations, or HarmonyOS design-rule reviews, use $harmonyos-ui-ux-guidelines.
When the task is true scaffolding, use scripts/scaffold_harmonyos_layout.py only after aligning the target layout with official docs or official sample structure.
Consult sources in this order:
HARMONYOS_DOCS_ROOTHARMONYOS_SAMPLES_ROOThttps://developer.huawei.com/consumer/cn/doc/ when local docs are unavailable or invalidAGENTS.md and existing project filesTreat HARMONYOS_DOCS_ROOT as valid when it points either to the docs repository root or directly to its zh-cn/ subtree. Treat HARMONYOS_SAMPLES_ROOT as valid when it points to the applications_app_samples repository root. If either environment variable is missing or invalid, continue with the remaining sources instead of failing immediately.
Do not use the current repository as the default architecture template for new projects. Use the repository only to extend or preserve an already existing codebase.
If the user asks for a complete app, sample app, demo, validation target, or "full" implementation but leaves key project choices unspecified, do not silently invent all defaults.
Read references/project-init-checklist.md, then resolve or state explicit defaults for:
If the user does not answer, choose the narrowest reasonable defaults and state them explicitly in the work.
Classify the target before creating files:
If the repository already has structure, extend it. Do not rebuild it around a different architecture unless the user explicitly asks for a redesign.
Before feature work, ensure the project has the official Stage-model build-first structure:
AppScope/app.json5build-profile.json5hvigorfile.tsbuild-profile.json5hvigorfile.tsentry/src/main/module.json5entry/src/main/ets/entryabilityentry/src/main/ets/pagesentry/src/main/resourcesresources/base/profile/These items come from official docs and default Stage-model project generation. Treat them as the baseline before introducing extra engineering layers.
After the official skeleton is in place, inspect official samples relevant to the target complexity.
For example, the official StateMgmtV2MVVM sample uses this shape under entry/src/main/ets/:
entry/src/main/ets/
entryability/
model/
pages/
settingability/
view/
viewmodel/
Treat that as a valid official MVVM-style sample pattern for larger ArkTS apps. In that pattern:
pages/ holds page entry and compositionview/ holds reusable presentational sectionsviewmodel/ holds UI-facing state transitionsmodel/ holds UI-facing modelssettingability/ are added only when the sample or feature set needs themFor system-capability or runtime-heavy apps, add only the extra implementation layers that the selected official sample pattern, required ability type, or native integration actually forces you to introduce. Common examples are:
service/ when orchestration, persistence, import, or bridge coordination no longer fits cleanly in page or ViewModel codeentryability/bridge/ or native-facing folders only when native integration is presentDo not pre-create project-specific folders in a generic scaffolding flow. Add source folders only when a concrete ability, integration boundary, or official sample pattern requires them.
For new UI work, default to ArkUI V2:
@ComponentV2@ObservedV2@Trace@Local@Param@Event@LocalBuilder when local composition is necessaryKeep pages focused on entry and composition. If the app grows beyond simple page logic, use official MVVM-style sample patterns before inventing a custom split.
If the harder question is the HarmonyOS UX itself, such as whether the app should use bottom tabs, side navigation, layered navigation, adaptive layout, multimodal controls, or specific interaction states, defer that decision to $harmonyos-ui-ux-guidelines before finalizing the UI structure.
When the project involves platform or native capabilities, define the boundary explicitly:
Do not patch over boundary issues with JSON deep copies, ad hoc listeners, or duplicated state fields.
Implement one end-to-end slice at a time:
Complete one slice before starting the next, unless the user explicitly wants scaffolding only.
Use staged verification:
Do not claim the project is complete only because files exist. Completion requires passing the relevant checks in references/verification-checklist.md.
Exit this phase only when:
Exit this phase only when:
Exit this phase only when:
Exit this phase only when:
@LocalBuilder parameter passing as a refresh-risk areabuild-profile.json5, app.json5, module.json5, and hvigorfile.ts before changing build commands$harmonyos-sdk-build-deployDo this in order:
pages/Do this in order:
view/ or views/, viewmodel/, or model/ only if official sample patterns match the target complexity$harmonyos-test-kit to add at least the minimum agreed test surfaceDo this in order:
For VPN, native bridge, or runtime-wrapper apps, also read references/system-client-pattern.md.
Use the repository's real commands rather than generic placeholders.
When the repository provides build and deploy instructions in AGENTS.md, follow those. When it does not, inspect the existing hvigor and module configuration first, then use $harmonyos-sdk-build-deploy to choose the correct official SDK path for compile, package, install, launch, or device-debug work.
For complex projects, report verification in three buckets:
Keep this skill focused on whether the project has reached the required verification stage. Keep detailed SDK tool selection and command guidance in $harmonyos-sdk-build-deploy.
When using this skill: