Streamlining Payroll: Automated HK Payroll ADW Calculation with AI
•AI

Streamlining Payroll: Automated HK Payroll ADW Calculation with AI

By Administrator
課程Vibe Coding & Tech Startup 創業課程結合 AI 輔助編程與創業思維：從靈感到原型、反覆迭代到真正上線，用清楚的步驟把想法做成可被使用的作品。前往課程頁查看完整大綱、上課方式與報名／諮詢方式。查看課程大綱與詳情 →

Managing HR operations for SMEs in Hong Kong often involves tedious, manual data entry and complex compliance requirements. The HK-Human-Resources-Skills repository is an Agent Skill project designed for use with AI agents (such as Cursor or Claude Code) to help HR teams and developers automate these critical tasks with precision and efficiency.

What is the HKHR Skills Toolkit?

The toolkit is a SQLite-backed system that provides structured command-line scripts for managing the full employee lifecycle. By acting as a specialized "skill" for AI assistants, it allows you to handle everything from payroll and compliance to IR56B readiness with simple, natural-language commands.

Key Capabilities

1. Automated HK Payroll ADW Calculation

The standout feature of this repository is its automated HK payroll ADW calculation. The ADW module reads dynamic Excel workbook structures, infers column mappings, and calculates Average Daily Wage (ADW) payouts. It includes:

  • Schema Inference: Automatically detects column names to reduce manual mapping.
  • Confidence Reporting: Provides a mapping_report.json to flag uncertainties.
  • Error Handling: Generates calculation warnings and CSV summaries for finance review.

2. Full Employee Lifecycle Management

  • Employee Module: Centralized record-keeping with SQLite for robust data storage.
  • Lifecycle Module: Manage onboarding and offboarding tasks using reusable templates.
  • Compliance: Track work eligibility and contract renewals with ease.
  • Leave Management: Handle leave applications, compensation leave, and policy tracking in alignment with standard HR web systems.
  • IR56B Readiness: Simplify tax filing preparation with automated readiness checks and Excel exports for employee profiles.

Getting Started

Prerequisites

  • Python 3.10+
  • A local environment (Windows, macOS, or Linux)

Installation

  1. Clone the repository and set up your virtual environment:
    python -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
  2. Initialize the database schema:
    python scripts/init_employee.py

How to Use with AI Agents

This project is built for AI-first workflows. To get the best results:

  1. Classify: Ask your AI assistant to determine if your task relates to ADW, EMPLOYEE, LEAVE, or other modules.
  2. Command: Request the AI to execute the specific script.
  3. Review: Always ask the AI to show the command before execution, especially for write operations.

Security and Privacy

Because HR data is highly sensitive, this toolkit is designed to keep data local. We recommend running it within a secure, local environment and avoiding the upload of sensitive employee PII to third-party cloud LLM APIs.

By leveraging this toolkit, you can transition from manual spreadsheet management to a standardized, automated, and audit-ready HR operation.