DHIS2 AI Kit

DHIS2 AI Kit provides a set of Claude Code skills and controlled scripts for working with DHIS2 safely and efficiently.

The main goals are:

• Use a single entry point: the dk skill.
• Prevent the agent from reading credentials directly.
• Avoid uncontrolled DHIS2 API calls using curl, fetch, axios, or inline scripts.
• Check the local probe cache before calling the API.
• Request only the fields required by the current task.
• Return compact, structured output to reduce token usage.
• Preserve user-owned skills, hooks, and project instructions.

Repository:

https://github.com/p3ild/dak

1. Requirements

• Node.js 18 or newer.
• Claude Code.

Check your Node.js version:

node --version

2. Installation

Option A: npx (recommended — one-shot)

Go to the root directory of the project where you want to use DHIS2 AI Kit:

cd /path/to/your-project

Run:

npx @devp2ild/dak

Option B: npm install (project dependency)

Add as a dev dependency, then run the installer:

npm install --save-dev @devp2ild/dak
npx dak

Or call the CLI directly:

node node_modules/@devp2ild/dak/dhis2-kit/setup/install.mjs

To update later:

npm update @devp2ild/dak
npx dak

The installer adds:

.claude/skills/dk
.claude/skills/dk-api
.claude/skills/dk-generate
.claude/skills/dk-setup
.claude/skills/dk-shared

.claude/hooks/dhis2-enforce-hook.cjs
dhis2-kit/

It also adds a managed instruction block to:

CLAUDE.md
AGENTS.md

Existing content outside the managed block is preserved.

3. Preview Changes Before Installation

Use --dry-run to inspect the planned changes without writing any files:

npx @devp2ild/dak --dry-run

Running a dry run first is recommended when the target project already contains custom skills or hooks.

4. Updating the Kit

Run the installation command again:

npx @devp2ild/dak

The installer will:

• Preserve credentials.
• Preserve the API probe cache.
• Preserve IMPLEMENTED.md.
• Update static kit files.
• Replace a skill directory when its source changes.
• Remove stale scripts that no longer exist in the new skill version.
• Preserve skills and hooks that do not belong to DHIS2 AI Kit.

5. Installing a Fixed Version

For stable and reproducible installations, pin a specific version:

npx @devp2ild/[email protected]

6. Uninstalling

Remote:

npx @devp2ild/dak --uninstall

Local:

bash dhis2-kit/setup/installer.sh --uninstall

The uninstaller removes only components owned by DHIS2 AI Kit.

The following runtime data is preserved:

dhis2-kit/memory/secret/
dhis2-kit/memory/probe-cache/
dhis2-kit/tmp/
dhis2-kit/memory/IMPLEMENTED.md

User-owned content in the following locations is not removed:

CLAUDE.md
AGENTS.md
.claude/settings.json
.claude/skills/
.claude/hooks/

Only the managed DHIS2 Kit instruction block is removed from CLAUDE.md and AGENTS.md.

7. Installed Project Structure

After installation, the target project will contain a structure similar to:

your-project/
├── CLAUDE.md
├── AGENTS.md
├── dhis2-kit/
│   ├── STRUCTURE.md
│   ├── _GUIDE.md
│   ├── AGENTS.md
│   ├── IMPORTANT.md
│   ├── SCRIPTS.md
│   ├── hooks/
│   │   └── dhis2-enforce-hook.cjs
│   ├── memory/
│   │   ├── IMPLEMENTED.md
│   │   ├── secret/
│   │   └── probe-cache/
│   └── tmp/
└── .claude/
    ├── settings.json
    ├── hooks/
    │   └── dhis2-enforce-hook.cjs
    ├── skills/
    │   ├── dk/
    │   ├── dk-api/
    │   ├── dk-setup/
    │   └── dk-shared/
    └── .dhis2-kit-install.json

8. Skill Responsibilities

dk

The main entry point for all DHIS2-related tasks.

The dk skill determines whether the task requires:

• Instance setup.
• Cache lookup.
• API probing.
• Controlled API execution.
• Metadata inspection.
• Project implementation work.

In most cases, users should invoke only dk.

dk-setup

Used when:

• No DHIS2 instance has been configured.
• A new instance must be added.
• Connectivity must be verified.
• Initial system information must be collected.
• The DHIS2 version must be detected.

dk-api

Used when:

• An endpoint must be discovered.
• A field must be verified.
• A response structure must be inspected.
• API metadata or schema must be probed.
• The probe cache does not contain enough information.

dk-shared

Contains the controlled runtime scripts used by the other skills.

The agent should not replace these scripts with arbitrary curl, fetch, axios, Python, or inline Node.js commands.

9. Configuring a DHIS2 Instance

Credentials are stored at:

dhis2-kit/memory/secret/instances.config.json

Example (credential only — metadata stored in probe-cache//_instance.json):

{
  "active": "your-instance.org",
  "instances": {
    "your-instance.org": {
      "baseUrl": "https://your-instance.org",
      "username": "your-username",
      "password": "your-password"
    }
  }
}

Do not commit the credentials file to Git.

Add the following rules to .gitignore:

dhis2-kit/memory/secret/*
!dhis2-kit/memory/secret/.gitkeep

Restrict filesystem permissions:

chmod 700 dhis2-kit/memory/secret
chmod 600 dhis2-kit/memory/secret/instances.config.json

The agent must not read the credentials file directly.

The controlled scripts in dk-shared read the configuration internally and return only the required result.

10. Using dk

Inside Claude Code, describe the task normally and explicitly ask the agent to use dk.

Examples:

Use dk to check the DHIS2 version and system information for the current instance.

Use dk to find the correct endpoint for exporting users with their user roles.

Use dk to verify whether the userGroups field is available from /api/users.

Use dk to retrieve the id, code, name, and parent of organisation units at level 3.

Use dk to inspect the /api/events response and identify the most suitable last-updated field.

Use dk and check the probe cache first. Do not psadfasdfasfdrobe the API again when the cache already contains enough information.

In most cases, you do not need to invoke dk-api, dk-setup, or dk-shared directly.

dk is the main dispatcher.

11. Standard DHIS2 Task Flow

The expected workflow is:

DHIS2 task
    ↓
Read dhis2-kit/AGENTS.md
    ↓
Resolve the target instance
    ↓
Check the probe cache
    ↓
Is the cache sufficient?
    ├── Yes
    │   ↓
    │ Perform the task directly
    │
    └── No
        ↓
      Perform the smallest necessary probe
        ↓
      Update the cache
        ↓
      Perform the task

Core rules:

1. The probe cache is trusted knowledge collected from the configured instance.

2. Probe the API only when the cache does not contain enough information.

3. If the cache already confirms that an endpoint or field is unavailable, do not repeat the same probe without a reason.

4. Request only the fields required by the task.

5. Do not return a large raw response when the task only needs a few values.

6. Never expose passwords, tokens, cookies, or authorization headers.

12. Common DHIS2 Tasks

Check Instance Information

Prompt:

Use dk to check the version, revision, and system information of the current DHIS2 instance.

Expected output should contain only useful information such as:

version
revision
server date
relevant database information

The full raw response is usually unnecessary.

Find the Correct Endpoint

Prompt:

Use dk to determine the correct endpoint for retrieving users together with userRoles and userGroups.

The expected process is:

1. Check the cache.
2. Inspect /api/users.
3. Determine whether userRoles and userGroups can be exported from that endpoint.
4. Find related endpoints when required.
5. Return a compact mapping.

Example result:

/api/users:
- id
- username
- displayName
- userRoles

/api/userGroups:
- id
- name
- users

Verify Whether a Field Exists

Prompt:

Use dk to verify whether authorities is available in the /api/userRoles response.

Or:

Use dk to check the cache first and determine whether /api/users supports the userRoles field.

When the cache already contains the answer, the API should not be called again.

Export Metadata

Prompt:

Use dk to retrieve id, code, name, valueType, and categoryCombo from dataElements.

The request should use field selection:

/api/dataElements?fields=id,code,name,valueType,categoryCombo[id,name]

The complete metadata object should not be requested unless the task actually requires it.

Retrieve Organisation Units

Prompt:

Use dk to retrieve organisation units at level 3 with id, code, name, and parent.

For large responses, the data should be written to a file and only a summary should be returned to the model.

Inspect a New API Endpoint

Prompt:

Use dk to inspect /api/example and identify:

- the root collection
- paging behavior
- the main fields
- the last-updated field
- whether delta filtering is supported

The probe should use a minimal page size where possible:

pageSize=1

This avoids downloading a large response only to inspect its structure.

Compare Fields Between Two APIs

Prompt:

Use dk to compare the fields from the legacy API with the new OpenAPI definition.

List:

- exact matches
- equivalent or similar fields
- fields without a match

When an OpenAPI document or schema already exists in the project, the agent should read the local file rather than making a network request.

Determine a Delta Pull Strategy

Prompt:

Use dk to determine whether this endpoint supports retrieving records changed since last_pull_at.

The analysis should check:

• lastUpdated filtering.
• updatedAt filtering.
• Paging support.
• Stable sorting.
• Watermark storage.
• Fallback behavior when the API does not support delta queries.

Inspect Relationships Across Endpoints

Prompt:

Use dk to determine how users, userRoles, and userGroups should be retrieved when they are not exported from the same endpoint.

The result should explain:

• Which endpoint owns each entity.
• Which IDs connect the entities.
• Whether an additional request is required.
• How to join the responses without downloading unnecessary fields.

Implement a DHIS2 Feature

Prompt:

Use dk to inspect the relevant DHIS2 API and implement the user-role export feature in this project.

The expected workflow is:

1. Inspect the existing project implementation.
2. Check the DHIS2 probe cache.
3. Probe only missing API knowledge.
4. Implement the feature using the current project architecture.
5. Run relevant tests or validation.
6. Record important implementation knowledge in IMPLEMENTED.md when applicable.

13. Running Scripts Manually

Normally, dk should select and run the appropriate script.

The scripts can also be run manually for debugging.

Call the DHIS2 API

node \
  .claude/skills/dk-shared/scripts/dhis2-api.mjs \
  "/api/system/info"

Check a Cached Field

node \
  .claude/skills/dk-shared/scripts/dhis2-cache.mjs \
  check-field \
  --prefix \
  --agent \
  /api/users \
  userRoles

Probe an Endpoint

node \
  .claude/skills/dk-api/scripts/dhis2-probe-wrapper.mjs \
  "/api/users?fields=id,username,userRoles"

Display the Instance Configuration Guide

node \
  .claude/skills/dk-shared/scripts/dhis2-guard.mjs --list

More commands are documented in:

dhis2-kit/SCRIPTS.md

14. Security Rules

The agent must not use arbitrary commands such as:

curl
wget
fetch
axios
node -e
python -c

to access DHIS2 or read credentials.

It must use the controlled scripts under:

.claude/skills/dk-shared/scripts/
.claude/skills/dk-api/scripts/

The enforcement hook monitors the following Claude Code tools:

Bash
Glob
Grep
Read
Edit
Write

The hook is registered in:

.claude/settings.json

Its entry point is:

.claude/hooks/dhis2-enforce-hook.cjs

The hook is a guardrail for agent behavior. It should not be treated as a complete operating-system security boundary.

For environments with stronger security requirements:

• Store credentials outside the repository.
• Allow only the controlled wrapper scripts to read credentials.
• Run the agent in a container or sandbox.
• Use a restricted operating-system account.
• Apply least-privilege access to the DHIS2 account.

15. Verifying the Hook

Check the hook syntax:

node --check \
  .claude/hooks/dhis2-enforce-hook.cjs

Inside Claude Code, inspect configured hooks:

/hooks

Verify that the PreToolUse matcher includes:

Bash|Glob|Grep|Read|Edit|Write

After changing .claude/settings.json, restart the Claude Code session.

16. Probe Cache

The probe cache is stored under:

dhis2-kit/memory/probe-cache/

Cache data should normally be grouped by DHIS2 version to avoid using schema knowledge from an incompatible instance.

Example:

dhis2-kit/memory/probe-cache/
└── 2.41/
    ├── _instance.json
    ├── api-users.json
    └── api-userRoles.json

Do not clear the cache for every task.

Refresh the cache only when:

• The DHIS2 version changes.
• An endpoint changes.
• The cache is known to be invalid.
• The user explicitly requests verification.
• The live response conflicts with cached information.

17. Output Guidelines

Output returned to the agent should be:

• Compact.
• Structured.
• Limited to the fields required by the task.
• Explicit about success or failure.
• Free of credentials and authorization information.

Good example:

{
  "ok": true,
  "endpoint": "/api/users",
  "field": "userRoles",
  "exists": true,
  "source": "cache"
}

Bad example:

{
  "users": [
    "... thousands of records ..."
  ],
  "headers": {
    "Authorization": "..."
  }
}

For large datasets, write the result to a file and return only a summary:

{
  "ok": true,
  "count": 15240,
  "outputFile": "dhis2-kit/tmp/users.json"
}

18. Project Instructions

The installer adds the following managed block to both CLAUDE.md and AGENTS.md:

<!-- dhis2-kit:start -->
## DHIS2 Kit

Before handling any DHIS2-related task, read and follow [dhis2-kit/AGENTS.md](dhis2-kit/AGENTS.md).
<!-- dhis2-kit:end -->

This ensures that the agent reads the kit rules before handling a DHIS2 task.

Content outside this block is preserved.

During uninstall, only this managed block is removed.

19. Preserving User Skills and Hooks

The installer manages only these skill paths:

.claude/skills/dk
.claude/skills/dk-api
.claude/skills/dk-generate
.claude/skills/dk-setup
.claude/skills/dk-shared

It manages only this hook:

.claude/hooks/dhis2-enforce-hook.cjs

Other user-owned components are preserved, for example:

.claude/skills/react-review/
.claude/skills/my-company-skill/
.claude/hooks/privacy-block.cjs
.claude/hooks/security-check.cjs

When updating .claude/settings.json, the installer removes or replaces only handlers that reference:

dhis2-enforce-hook.cjs

Other hook handlers remain unchanged.

20. Protected Runtime State

The installer does not overwrite or uninstall:

dhis2-kit/memory/secret/
dhis2-kit/memory/probe-cache/
dhis2-kit/tmp/

The following file is created only when it does not already exist:

dhis2-kit/memory/IMPLEMENTED.md

After creation, project-specific content in IMPLEMENTED.md is preserved across updates.

21. Troubleshooting

The dk Skill Is Not Detected

Check that the skill exists:

ls -la .claude/skills/dk
cat .claude/skills/dk/SKILL.md

Restart Claude Code after installing or updating skills.

The Hook Does Not Run

Check the settings:

cat .claude/settings.json

Check the deployed hook:

ls -la .claude/hooks/

Validate its syntax:

node --check \
  .claude/hooks/dhis2-enforce-hook.cjs

Inside Claude Code, inspect the loaded hooks:

/hooks

CLAUDE_PROJECT_DIR Is Empty in a Terminal

CLAUDE_PROJECT_DIR is injected by Claude Code when it executes a hook.

The following command may fail in a normal shell:

node ${CLAUDE_PROJECT_DIR}/.claude/hooks/dhis2-enforce-hook.cjs

For manual testing, use:

export CLAUDE_PROJECT_DIR="$(pwd)"

node \
  "${CLAUDE_PROJECT_DIR}/.claude/hooks/dhis2-enforce-hook.cjs"

Or:

node "$(pwd)/.claude/hooks/dhis2-enforce-hook.cjs"

Credentials Can Still Be Read

Verify that the hook:

• Matches the Read tool.
• Reads the path from tool_input.file_path.
• Resolves both relative and absolute paths.
• Returns permissionDecision: "deny".
• Does not only print a warning and exit successfully.

Credentials should remain at:

dhis2-kit/memory/secret/instances.config.json

They must not be read directly by the agent.

The Installer Reports a Conflict

Preview the operation:

npx @devp2ild/dak --dry-run

When the conflict is an old DHIS2 AI Kit file that can safely be replaced:

npx @devp2ild/dak --force

Do not use --force before reviewing custom content at the conflicting path.

Remote Installation Does Not Support --link

This is intentional.

The remote installer downloads the repository into a temporary directory and removes that directory after installation.

A symlink to that temporary source would immediately become invalid.

Use the default copy mode for remote installation:

npx @devp2ild/dak

Use link mode only from a persistent local clone:

bash dhis2-kit/setup/installer.sh \
  --link \
  --target /path/to/project

22. Complete Usage Example

User request:

Use dk to determine whether /api/users can export both userRoles and userGroups.

Check the probe cache first and do not repeat API probes when the cache already contains enough information.

Expected agent workflow:

1. Read dhis2-kit/AGENTS.md.
2. Resolve the configured instance and DHIS2 version.
3. Check the probe cache for:
   - /api/users userRoles
   - /api/users userGroups
4. Return the cached result when sufficient.
5. Probe only the missing field when required.
6. Update the cache.
7. Return a compact summary.

Example result:

/api/users:
- userRoles: available
- userGroups: not exported directly

To retrieve user groups:
- use /api/userGroups
- request fields=id,name,users[id]

Sources:
- userRoles: probe cache
- userGroups: new API probe

23. Quick Start

Install:

npx @devp2ild/dak

Configure the instance:

dhis2-kit/memory/secret/instances.config.json

Restart Claude Code.

Then submit a task such as:

Use dk to handle this DHIS2 task: ...