skill-author

Guide for authoring new AI agent skills following the conventions of this repository.

When to Use

• User wants to create a new skill directory with SKILL.md
• User wants to update an existing skill's description, workflow, or boundary table
• User wants to add reference documents to a skill's references/ directory
• User wants to add code examples to a skill's assets/ directory
• User asks about skill structure, frontmatter fields, or boundary conventions

Do not force this skill onto general HarmonyOS development tasks — use the domain skills (arkts-helper, arkts-debug, arkts-build, arkts-ndk-dev, harmony-fetch) instead.

Boundary with Other Skills

This skill covers skill authoring conventions, not HarmonyOS development content. When the task involves the following, cross-reference the corresponding skill:

Workflow (Follow Strictly)

1. Determine Skill Scope

Before creating a new skill, check whether the topic overlaps with existing skills:

If the new topic fits within an existing skill's scope, extend that skill (add references, update SKILL.md) rather than creating a new one.

2. Create the Directory Structure

<skill-name>/
  SKILL.md              # Required
  references/           # Required. Must include INDEX.md.
  assets/               # Optional. Code examples (.ets, .cpp, etc.)
  scripts/              # Optional. Utility scripts (e.g., fetch_doc.py)

3. Write SKILL.md

Frontmatter (YAML, required fields):

---
name: <skill-name>
description: <comprehensive trigger condition — list every keyword, error code, API name, and scenario that should activate this skill>
---

The description is critical. The agent uses it to decide when to load the skill. Under-specifying it means the skill won't activate when needed. Include:

• Specific error codes or messages
• API names, decorators, classes
• Scenario keywords
• Related concepts and synonyms

Body sections (in order):

1. # Skill Name — one-line purpose statement
2. ## When to Use — bullet list of activation scenarios
3. ## Boundary with Other Skills — table with Issue Type | Cross-reference Skill | Boundary. Must reference all four other domain skills where boundaries exist.
4. ## Workflow (Follow Strictly) — numbered steps the agent must follow

4. Create references/INDEX.md

# INDEX - <skill-name> Reference Documentation

> **Must read first**: Before any <skill-name> task, **read this file first**, then load the corresponding document based on the task type mapping table below.

## Document Roles

| File | Role |
| --- | --- |
| `01-topic.md` | Description of first topic |
| `02-topic.md` | Description of second topic |

## Reading Paths by Scenario

| Scenario | Required Reading |
| --- | --- |
| Scenario A | `01-topic.md` |
| Scenario B | `02-topic.md` → `03-topic.md` |

5. Add Reference Documents

Each doc in references/ must start with:

# Document Title

> **上游 URL**: https://developer.huawei.com/consumer/cn/doc/...
> **抓取时间**: YYYY-MM-DD

[Content follows, using ## / ### heading hierarchy matching upstream]

6. Update Boundary Tables in Other Skills

After creating a new skill, update the ## Boundary with Other Skills table in all four existing domain skills to include the new skill where boundaries exist.

7. Update README.md

Add the new skill to the Skills table in README.md.