arkts-skills/AGENTS.md

AGENTS.md - OpenCode Skills Repository

This repository contains AI coding agent skills for HarmonyOS/ArkTS development. Skills teach AI assistants how to build, deploy, and develop HarmonyOS applications.

Repository Structure

skills/
├── arkts-development/          # ArkTS/ArkUI development skill
│   ├── SKILL.md               # Main skill definition
│   ├── assets/                # Code templates (.ets files)
│   └── references/            # API docs, migration guide, patterns
└── harmonyos-build-deploy/    # Build & deploy skill
    ├── SKILL.md               # Main skill definition
    └── references/            # Device installation guide

Build/Lint/Test Commands

This is a documentation repository - no build system for the repo itself. However, the skills document these HarmonyOS CLI tools:

Build Commands (hvigorw)

# Incremental build (default for development)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

# Clean build
hvigorw clean --no-daemon
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

# Build single module (faster iteration)
hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon

# Run tests
hvigorw onDeviceTest -p module=entry -p coverage=true    # On-device test
hvigorw test -p module=entry                              # Local test

Package Manager (ohpm)

ohpm install --all              # Install all dependencies
ohpm clean && ohpm cache clean  # Deep clean

Code Linter (codelinter)

codelinter                      # Check current project
codelinter --fix                # Check and auto-fix
codelinter -f json -o report.json  # JSON output
codelinter -i                   # Incremental (Git changes only)
codelinter --exit-on error,warn # CI/CD with exit codes

Device Commands (hdc)

hdc list targets                # List devices (returns UDID)
hdc -t <UDID> file send <local> <remote>  # Push files
hdc -t <UDID> shell "bm install -p <path>" # Install app
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>" # Launch app

Code Style Guidelines

ArkTS Language Constraints

ArkTS is stricter than TypeScript. These are prohibited:

Prohibited	Use Instead
any, unknown	Explicit types, interfaces
var	let, const
Dynamic property obj['key']	Fixed object structure
for...in, delete, with	for...of, array methods
#privateField	private keyword
Structural typing	Explicit implements/extends

Naming Conventions

Element	Convention	Example
Components (struct)	PascalCase	HomePage, UserCard
Methods	camelCase	loadData(), handleClick()
Properties/Variables	camelCase	isLoading, userName
Interfaces	PascalCase	UserInfo, ApiResponse
Constants	camelCase or UPPER_SNAKE	maxRetries, API_URL
Files (skill docs)	kebab-case	api-reference.md
Skill directories	kebab-case	arkts-development

Type Annotations

Always use explicit type annotations:

// Required: Explicit types on declarations
@State isLoading: boolean = false;
@State items: ItemType[] = [];

// Required: Return types on methods
async loadData(): Promise<void> { }
navigateToDetail(item: ItemType): void { }

// Required: Parameter types
ForEach(this.items, (item: ItemType) => { ... }, (item: ItemType) => item.id)

Component Structure

Follow this standard component layout:

@Entry
@Component
struct ComponentName {
  // 1. State decorators
  @State isLoading: boolean = false;
  @State errorMessage: string = '';

  // 2. Lifecycle methods
  aboutToAppear(): void { this.loadData(); }
  aboutToDisappear(): void { /* cleanup */ }

  // 3. Business methods
  async loadData(): Promise<void> { }

  // 4. Builder methods (reusable UI blocks)
  @Builder ItemCard(item: ItemType) { }

  // 5. Build method (always last)
  build() { }
}

Error Handling Pattern

async loadData(): Promise<void> {
  this.isLoading = true;
  try {
    // async operation
  } catch (error) {
    this.errorMessage = 'Failed to load data';
  } finally {
    this.isLoading = false;
  }
}

Import Style

Use HarmonyOS Kit imports:

import { router } from '@kit.ArkUI';
import { http } from '@kit.NetworkKit';
import { preferences } from '@kit.ArkData';

Skill File Format

Each skill follows this structure:

---
name: skill-name
description: Detailed description for AI agent matching
---

# Skill Title

## Quick Start / Quick Reference
## Main Content Sections
## Troubleshooting
## Reference Files

YAML Frontmatter

Required fields:

• name: kebab-case identifier matching directory name
• description: Detailed description for AI agent matching (trigger keywords)

Documentation Conventions

• Use tables for command references and parameters
• Include code blocks with language specifiers (typescript, bash)
• Cross-reference related skills and reference files
• Use bilingual content (Chinese/English) for HarmonyOS context
• Structure: Quick Reference first, then detailed sections

File Organization

• Main skill definition: SKILL.md (uppercase)
• Code templates: assets/*.ets
• Reference documentation: references/*.md
• All filenames: kebab-case

Common Patterns

State Management Decorators

Decorator	Direction	Usage
@State	Internal	Component's own mutable state
@Prop	Parent → Child	One-way binding (child copy)
@Link	Parent ↔ Child	Two-way binding (pass with $var)
@Provide/@Consume	Ancestor → Descendant	Cross-level state sharing

Layout Components

Column({ space: 10 }) { }  // Vertical layout
Row({ space: 10 }) { }     // Horizontal layout
Stack() { }                 // Overlay layout
List({ space: 10 }) { }    // Scrollable list

ForEach Pattern

Always provide explicit types and key generator:

ForEach(this.items, (item: ItemType) => {
  ListItem() { Text(item.title) }
}, (item: ItemType) => item.id)  // Key generator for efficient updates