AGENTS.md

This file provides guidance to the AI agent when working with code in this repository.

Project Overview

This is a knowledge-base repository of AI agent skills for OpenHarmony / HarmonyOS app development. There is no build system, no linter, no formatter, and no automated test suite. Each skill is a self-contained directory at the repo root with a SKILL.md and supporting reference documents. Skills are symlinked (or junctioned on Windows) into agent platform directories (.qoder/skills/, .trae/skills/, .codeartsdoer/skills/).

Skill Authoring Conventions

Each skill directory follows this structure:

<skill-name>/
  SKILL.md              # Required. Manifest + instructions.
  references/           # Offline doc copies. Must include INDEX.md. (Offline-doc skills only — see below.)
  assets/               # Optional. Code examples (.ets, etc.)
  scripts/              # Optional. Utility scripts.
  evals/                # Optional. Trigger/behavior test cases (evals.json).

Two skill shapes exist:

• Offline-doc skills carry an offline snapshot of official docs under references/ (the majority: arkts-helper, arkts-debug, arkts-build, arkts-ndk-dev, harmony-design, create-app-icon, understand-hmos, arkts-crash-diagnosis).
• Online-type / meta skills have no references/ (harmony-fetch fetches live docs; skill-author / validate-skill are process guides; create-hmos-project ships a template under application/ instead).
• Orchestration skills (hmos-flow) additionally carry agents/ — Markdown role cards whose frontmatter (name, description) plus body-as-system-prompt is the native subagent format on platforms that support custom subagents (e.g. ZCode). On platforms without a subagent registry, the same cards are referenced by path in the dispatch prompt. Role cards are platform-neutral by design: keep them pure Markdown, no platform-specific keys.
  • Platform-specific subagent knobs (model, tool permissions, turn caps) live in platforms/<platform>/role-config.json and are injected at deploy time by scripts/deploy_agents.py, so the kernel stays portable.

SKILL.md frontmatter (YAML, required fields: name, description):

• name: matches the directory name exactly
• description: the trigger condition — must be comprehensive. List every keyword, error code, API name, and scenario that should activate this skill. The agent uses this to decide when to load the skill, so under-specifying it means the skill won't activate.
• Optional: version, license, metadata (author, generatedBy)

SKILL.md body must include these sections:

1. Title (# Skill Name) — one-line purpose statement
2. When to Use — bullet list of activation scenarios
3. Boundary with Other Skills — table with columns: Issue Type | Cross-reference Skill | Boundary. Must reference all other skills in the repo where boundaries exist.
4. Workflow — numbered steps the agent must follow strictly (e.g., "read INDEX.md first", "load the matching reference", "apply the fix")

Reference docs (references/*.md):

• Must include INDEX.md as the entry point — lists every doc's role and reading paths by scenario ("Must read first" note may be English or its Chinese equivalent 「唯一入口，必读」)
• Each doc starts with a source header in one of these forms:
  • Standard: > **上游 URL**: ... + > **抓取时间**: YYYY-MM-DD
  • Enhanced (preferred when known): > 来源：官方《标题》(URL)（文档版本号），核实于 YYYY-MM-DD — the verified doc version enables version-level traceability
  • Aggregated: catalog-level URL with 聚合自 ... catalog note, for skills merging many leaf docs
• Exemptions: original-authored reference content (e.g. curated error catalogs in arkts-debug) and scripts/templates carry no upstream header; arkts-crash-diagnosis references carry the upstream knowledge-base URL instead
• Use ##/### heading hierarchy matching the upstream doc structure
• Content language matches the upstream source (currently Chinese for HarmonyOS docs)

Code examples (assets/*.ets):

• Use BAD vs GOOD pattern with clear labels
• Minimal, focused on one error/fix per file
• Non-code assets (.svg / .json / .json5 templates) are exempt from the BAD/GOOD rule

Boundary table integrity (all skills):

• Every skill name referenced in a boundary table must exist as a repo directory — the repo-root README.md Skills table is the authoritative inventory
• Overlapping skills must reference each other (forward + reverse)
• INDEX.md form may vary (Document Roles / 文档角色清单 tables); what matters is per-doc roles + scenario-to-doc mapping. A skill whose SKILL.md embeds a complete catalog (e.g. arkts-debug's 28-category index) is an acceptable variant

Scripts (scripts/):

• Must be self-contained (no imports from other skills or repo-only paths)
• Invoke Python as python in examples (Windows lacks a working python3 alias); note the cross-platform variant where relevant
• Node scripts: syntax-check with node --check before committing

Validation

There is no automated test suite. Layered validation:

1. Structural: use validate-skill (its Scriptable Checks section lists the mechanical checks — frontmatter, dangling skill refs, file links, source headers, BAD/GOOD markers).
2. Trigger/behavior: evals/evals.json under a skill holds trigger test cases; run a representative case in a fresh session and confirm the skill activates and the workflow is followed. Repo-wide trigger cases: evals/cases.json at repo root.
3. A skill change is done when structural checks pass AND at least one representative prompt activates the right skill and produces the documented workflow output.

Git / PR Conventions

• Single main branch, no feature branches
• Commit messages follow Conventional Commits: feat:, fix:, docs:, chore:, refactor:
• Scope is the skill name when applicable: docs(arkts-helper): add concurrency section
• PRs should describe which skill changed and why

Markdown Conventions

• Tables use GitHub-flavored markdown with | --- | separators
• Notes/warnings use blockquotes (> **Note**: ...)
• Code blocks must have language tags (```ets, ```bash, ```typescript, etc.)
• Cross-references between skills use inline links: `skill-name`
• Reference docs preserve the heading hierarchy of the upstream source
• Do not add emojis to any files