# Arkuix Module Adapter

> ArkUIX Module Adapter Skill

- Skill: `openharmonyinsight/arkuix-module-adapter` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/arkuix-module-adapter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/arkuix-module-adapter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openharmonyinsight (https://skillmd.com/u/openharmonyinsight)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openharmonyinsight/arkuix-module-adapter

---


# ArkUIX Module Adapter Skill

## Overview

Guide OHOS modules through cross-platform adaptation with automated analysis and code generation. This skill transforms Claude into a specialized adaptation assistant with domain expertise in OHOS/ArkUI-X architecture.

## Quick Start

```
User: "I need to adapt @ohos.data.preferences module"
```

The skill automatically guides through all 6 phases of adaptation.

## 6-Phase Workflow

### Phase 1: Information Collection

Collects minimal information upfront (module name), then lazily collects additional details (repository name, storage path) only when needed.

**Output**: Module identification information

### Phase 2: Code Existence Check & Sync

Intelligently checks if OHOS code already exists before syncing. Avoids redundant operations.

**Decision Tree**:
1. Check `.repo/manifests/openharmony-master.xml`
2. Check `plugins/` directory
3. Only sync if both checks fail (with repository verification on GitCode)

**Output**: Sync status or repository verification results

### Phase 3: API Interface Analysis

Analyzes `.d.ts` file to determine `@crossplatform` coverage.

**Metrics**:
- Total interface count (by category)
- Adapted vs needs adaptation counts
- Coverage percentage
- Detailed list of interfaces needing adaptation

**Output**: Comprehensive API statistics with coverage progress bar

**Automation**: `scripts/dts_analyzer.py interface/sdk-js/api/@ohos.{module}.d.ts`

### Phase 4: Architecture Analysis

Analyzes OHOS module code composition and platform dependencies.

**Analysis Dimensions**:
- Code volume statistics (NAPI, business logic, platform-specific)
- Platform dependency ratio
- Internal and external dependencies
- **Platform implementation necessity** (C/C++ native vs platform-specific code)
- Architecture diagrams (module structure, dependencies, call flow)

**Key Rule**: C/C++ Cross-Platform Native Support
- Analyzes whether module actually requires Android/iOS platform code
- Many data modules (preferences, RDB, crypto) are pure C/C++ and require zero platform-specific implementation
- Only path/configuration differences needed (~50 lines per platform)

**Output**: Detailed code composition and dependency analysis

**Automation**: `scripts/architecture_analyzer.py foundation/{module_path}`

### Phase 5: Architecture Recommendation

Recommends adaptation mode based on analysis: **OHOS Reuse** / **Independent** / **Hybrid**

**Decision Matrix**:

| Mode | Code Reuse | New Code | Time | Best For |
|------|------------|----------|------|----------|
| OHOS Reuse | 90-95% | 500-800 lines | 4-6 weeks | Data-focused (preferences, kv_store) |
| Hybrid | 60-80% | 1,500-2,500 lines | 6-10 weeks | Mixed (location, sensor) |
| Independent | 10-30% | 4,000-6,000 lines | 10-16 weeks | Platform-heavy (BLE, pasteboard) |

**Output**: Recommended mode with rationale and effort estimates

### Phase 6: Implementation Guidance

Provides actual implementation code with complete examples for:
- Pure virtual interface (OHOS repo)
- OHOS thin wrapper (100% forwarding)
- Android JNI adapter (complete with error handling)
- iOS Objective-C++ adapter (complete with @try-@catch)
- Build configuration (GN templates)
- Unit tests

**Output**: Production-ready code with comprehensive error handling

**Automation**: `scripts/code_generator.py {module} {repo} --api-version {ver}`

## Key Features

### 🤖 Automated Scripts

All scripts are in `scripts/` directory:

```bash
# Analyze .d.ts coverage
python3 scripts/dts_analyzer.py interface/sdk-js/api/@ohos.data.preferences.d.ts

# Analyze module architecture
python3 scripts/architecture_analyzer.py foundation/distributeddatamgr/preferences

# Generate configuration files (dry-run)
python3 scripts/code_generator.py data/preferences distributeddatamgr_preferences --api-version 23 --dry-run

# Apply changes
python3 scripts/code_generator.py data/preferences distributeddatamgr_preferences --api-version 23
```

### 📚 Progressive Disclosure

Core workflow in SKILL.md (this file), detailed content in references:

- **Phase Details**: `references/phase{1-6}*.md`
- **Architecture Modes**: `references/architecture-modes.md`
- **Code Examples**: `references/code-examples.md`
- **Templates**: `assets/templates/` (code templates for reuse)

### 🎯 Three Architecture Modes

#### OHOS Reuse Mode (90-95% reuse)

For data-focused modules with minimal platform dependencies.

**Characteristics**:
- Platform-independent business logic >90%
- Thin platform adapters (JNI/ObjC++)
- Zero OHOS runtime overhead
- **C/C++ Native modules may require zero platform code** (up to 100% reuse)

**Example Modules**: preferences, kv_store, http

#### Independent Implementation Mode (10-30% reuse)

For modules with heavy platform API dependencies.

**Characteristics**:
- Platform-specific code >70%
- Native framework integration
- Each platform has own implementation

**Example Modules**: bluetooth, pasteboard, camera

#### Hybrid Mode (60-80% reuse)

For mixed data/platform logic modules.

**Characteristics**:
- Extract common data structures
- Service abstraction layer
- Shared business logic

**Example Modules**: geolocation, sensor, request

## Implementation Checklist

Use this checklist to track adaptation progress:

### Phase 1: Information Collection
- [ ] Module name collected
- [ ] Repository name verified (if needed)

### Phase 2: Code Sync
- [ ] Repository verified on GitCode
- [ ] Code synced (if needed)
- [ ] Plugin structure created (if needed)

### Phase 3: API Analysis
- [ ] .d.ts file analyzed
- [ ] Coverage percentage calculated
- [ ] Interfaces needing adaptation listed

### Phase 4: Architecture Analysis
- [ ] Code volume statistics collected
- [ ] Platform dependency ratio calculated
- [ ] Dependencies identified
- [ ] **Platform implementation necessity analyzed** (C/C++ native vs platform-specific)

### Phase 5: Architecture Recommendation
- [ ] Architecture mode selected
- [ ] Developer confirms choice

### Phase 6: Implementation
- [ ] Pure virtual interface defined (OHOS repo)
- [ ] OHOS thin wrapper implemented (OHOS repo)
- [ ] Android adapter implemented (Plugin repo)
- [ ] iOS adapter implemented (Plugin repo)
- [ ] Build configuration updated
- [ ] Configuration files generated (4 files)
- [ ] Unit tests written
- [ ] Compilation successful (all platforms)
- [ ] Tests passing

## Mandatory Configuration Files

After code generation, ensure all 4 files are updated:

- [ ] `plugins/plugin_lib.gni` - Module entry
- [ ] `interface/sdk/plugins/api/apiConfig.json` - Library configuration
- [ ] `build_plugins/sdk/arkui_cross_sdk_description_std.json` - Build entries
- [ ] `interface/sdk-js/api/@ohos.{module}.d.ts` - @crossplatform annotations

## Troubleshooting

**Repository not found on GitCode?**
- Browse https://gitcode.com/org/openharmony/repos manually
- Try naming pattern: `{subsystem}_{module}` or `{module}`

**Validation failed?**
- Check all 4 mandatory files exist
- Verify module name format (use forward slashes)
- Ensure .d.ts file path is correct

**Build errors?**
- Check GN configuration syntax
- Verify dependency declarations
- Check for missing includes

## Related Skills

- **arkuix-api-adapter** - For adapting individual API methods within a module

## Tips

1. **Start Small**: Try with a simple module first (e.g., preferences)
2. **Use Dry-Run**: Always use `--dry-run` flag before applying changes
3. **Verify Repository**: Always verify repository exists before syncing
4. **Read References**: Consult detailed references for complex phases
5. **Run Tests**: Always run tests after implementation