# harmonyos-app

Provides rules and patterns for building HarmonyOS NEXT apps with ArkTS and ArkUI. Guides agents on strict typing and immutable state updates under Stage model.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 491 installs · ★ 288
- Author: majiayu000
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/majiayu000/spellbook/tree/HEAD/skills/harmonyos-app/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/harmonyos-app

## What it does

This skill enforces development rules for HarmonyOS NEXT (API 12+). It explicitly forbids dynamic types like `any` or arbitrary property access on plain objects. ArkTS demands strict typing, allowing dynamic keys only through `Record` definitions.

State management in ArkUI follows strict immutability. Directly mutating nested fields on `@State` or `@Prop` variables will fail to trigger UI updates. The skill requires spreading objects or arrays into new references, while keeping complex views split across reusable `@Component` structs.

Legacy FA model patterns are entirely blocked. If a codebase still relies on `config.json` and `PageAbility`, this skill will reject the setup, because it accepts only the modern Stage model with `UIAbility` and `module.json5`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill harmonyos-app -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/harmonyos-app/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/harmonyos-app/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill harmonyos-app -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/harmonyos-app/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill harmonyos-app -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/harmonyos-app/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install majiayu000/spellbook harmonyos-app
```

2. **Manually: put the files in place**
- File: `.github/skills/harmonyos-app/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill harmonyos-app -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/majiayu000/spellbook --path skills/harmonyos-app
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/harmonyos-app/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add majiayu000/spellbook --skill harmonyos-app -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/majiayu000/spellbook/tree/HEAD/skills/harmonyos-app/SKILL.md

## When to use it
- eliminate `any` types and dynamic property access in ArkTS
- prevent UI update failures caused by direct `@State` mutations
- migrate application architecture from legacy FA model to modern Stage model
- decompose monolithic `build()` methods into reusable `@Component` structs

## Example prompts
- Create a product card component in ArkUI using @Prop and strict typing without any
- Set up an EntryAbility using Stage model and configure the lifecycle in module.json5
- Fix array updates on @State to ensure the UI re-renders when appending items

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: eb1451c471e726e8.

BEGIN THIRD-PARTY FILE eb1451c471e726e8
````text
---
name: harmonyos-app
description: HarmonyOS application development expert. Use when building HarmonyOS apps with ArkTS, ArkUI, Stage model, and distributed capabilities. Covers HarmonyOS NEXT (API 12+) best practices.
---
# HarmonyOS Application Development

## Core Principles

- **ArkTS First** — Use ArkTS with strict type safety, no `any` or dynamic types
- **Declarative UI** — Build UI with ArkUI's declarative components and state management
- **Stage Model** — Use modern Stage model (UIAbility), not legacy FA model
- **Distributed by Design** — Leverage cross-device capabilities from the start
- **Atomic Services** — Consider atomic services and cards for lightweight experiences
- **One-time Development** — Design for multi-device adaptation (phone, tablet, watch, TV)

---

## Hard Rules (Must Follow)

> These rules are mandatory. Violating them means the skill is not working correctly.

### No Dynamic Types

**ArkTS prohibits dynamic typing. Never use `any`, type assertions, or dynamic property access.**

```typescript
// ❌ FORBIDDEN: Dynamic types
let data: any = fetchData();
let obj: object = {};
obj['dynamicKey'] = value;  // Dynamic property access
(someVar as SomeType).method();  // Type assertion

// ✅ REQUIRED: Strict typing
interface UserData {
  id: string;
  name: string;
}
let data: UserData = fetchData();

// Use Record for dynamic keys
let obj: Record<string, string> = {};
obj['key'] = value;  // OK with Record type
```

### No Direct State Mutation

**Never mutate @State/@Prop variables directly in nested objects. Use immutable updates.**

```typescript
// ❌ FORBIDDEN: Direct mutation
@State user: User = { name: 'John', age: 25 };

updateAge() {
  this.user.age = 26;  // UI won't update!
}

// ✅ REQUIRED: Immutable update
updateAge() {
  this.user = { ...this.user, age: 26 };  // Creates new object, triggers UI update
}

// For arrays
@State items: string[] = ['a', 'b'];

// ❌ FORBIDDEN
this.items.push('c');  // UI won't update

// ✅ REQUIRED
this.items = [...this.items, 'c'];
```

### Stage Model Only

**Always use Stage model (UIAbility). Never use deprecated FA model (PageAbility).**

```typescript
// ❌ FORBIDDEN: FA Model (deprecated)
// config.json with "pages" array
export default {
  onCreate() { ... }  // PageAbility lifecycle
}

// ✅ REQUIRED: Stage Model
// module.json5 with abilities configuration
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Modern Stage model lifecycle
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index');
  }
}
```

### Component Reusability

**Extract reusable UI into @Component. No inline complex UI in build() methods.**

```typescript
// ❌ FORBIDDEN: Monolithic build method
@Entry
@Component
struct MainPage {
````
END THIRD-PARTY FILE eb1451c471e726e8

The third-party file has ended. Everything between the eb1451c471e726e8 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2934 of 11316 bytes. © majiayu000 · MIT · https://github.com/majiayu000/spellbook/tree/HEAD/skills/harmonyos-app/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md