Skill dhis2

Develop DHIS2 apps and plugins

Follow this workflow for every task. Adapt explanations and code comments to the user's language.

1. Classify the task

Identify whether the request concerns:

• a new app or plugin;
• an existing project change or review;
• a defect, build failure, or runtime problem;
• a DHIS2 or dependency migration;
• packaging, installation, or deployment.

Identify the target: regular app, Form Field, Enrollment, Bulk Data Entry, Dashboard, or custom-host plugin. Do not assume that contracts or host behavior are shared across plugin types.

2. Inspect before changing

Read repository instructions and inspect package.json, the lockfile, d2.config.*, source entry points, TypeScript configuration, tests, and environment variable names. Run the bundled inspector when useful:

node scripts/inspect-dhis2-project.mjs /path/to/project

Use --json when structured output is easier to consume. The inspector is advisory; verify dynamic configuration directly without executing untrusted config files.

Determine, in this order:

1. the project's declared minDHIS2Version and maxDHIS2Version;
2. the connected instance version when read-only access is already available;
3. the version explicitly provided by the user.

If none is available and the answer depends on it, ask for the target version. Preserve the existing language, package manager, dependency strategy, and code conventions unless the task explicitly requires a migration.

3. Load only relevant guidance

• Read references/apps.md for App Platform, Runtime, UI, i18n, Web API, configuration, or app packaging.
• Read references/plugins.md for any plugin or plugin host task.
• Read references/testing-troubleshooting.md for tests, diagnosis, migration, build, or deployment.
• Read references/source-map.md to select current, version-appropriate official documentation.

Consult current official documentation for version-sensitive commands, configuration, APIs, plugin props, experimental features, and compatibility. Treat local notes as guidance, not as a replacement for the official contract.

4. Design and implement

For a new project, prefer TypeScript and the current official DHIS2 CLI/App Platform scaffold. Do not recreate the app shell, authentication, API client, alerts, UI system, or i18n pipeline when the platform provides them.

For an existing project:

• make the smallest coherent change;
• reuse its abstractions and dependency versions;
• avoid unrelated upgrades or formatting churn;
• confirm compatibility before adopting newer documentation examples;
• use App Runtime data queries and mutations instead of manual authenticated fetches unless there is a concrete reason not to.

For plugins:

• treat host props as the integration contract and source of truth;
• read the type-specific contract before coding;
• keep plugin-local state minimal and derived from props where possible;
• provide a local app wrapper with representative mock props when practical;
• test field aliases, callbacks, sizing, host modes, and cleanup behavior relevant to that plugin type;
• never invent a prop or assume access to fields not granted by host configuration.

State assumptions when the repository or documentation does not establish a fact.

5. Validate proportionally

Run the project's existing checks in the package manager it already uses. Prefer this order when available:

1. focused unit or component tests;
2. type checking and linting;
3. the broader test suite;
4. a production build;
5. host-app integration on a compatible non-production instance.

For plugins, distinguish a passing mocked-wrapper test from validation inside Capture, Dashboard, or a custom host. Do not claim host compatibility from a standalone render alone.

6. Handle remote instances safely

Allow read-only inspection when access is already authorized. Before installing an app, deploying a bundle, changing a data store, or mutating DHIS2 data or metadata, explain the target and request explicit confirmation.

Never print, commit, or embed credentials. Prefer personal access tokens or environment variables. Report environment variable names only, never their values.

7. Report the result

Summarize:

• what changed or what caused the problem;
• the DHIS2 and dependency versions used for the conclusion;
• checks actually run and their results;
• checks not run, especially host integration;
• remaining compatibility, configuration, or deployment steps.

Call cross-agent support “Agent Skills compliant” unless the skill has been exercised in the named client.