Streamlining Expatriate Tax Planning with a Skill

Where this fits

A global HR team is seconding a German engineer to Shanghai for 18 months. They need to determine his tax residency status, apply the China-Germany social security agreement, and calculate any foreign tax credit—all while juggling payroll deadlines. This skill turns that messy, multi-jurisdiction puzzle into a structured workflow an agent can execute end-to-end.

Why agents benefit

• Residency determination logic: Automates the 183-day count, six-year rule, and permanent home assessment using the README's explicit criteria, so agents don't hallucinate thresholds.
• Treaty article mapping: Directly links to OECD/UN model articles (15, 16, 19, 23) with China-specific interpretations, letting agents pick the right clause without flipping through statutes.
• Social security agreement lookup: Hardcodes the list of bilateral agreements (DE, KR, DK, FI, CA, JP) and their typical duration limits, enabling agents to verify whether a new hire qualifies for exemption.
• Credit optimization: Provides the formula flow for calculating foreign tax credit limits and applying the exemption method, turning a math-heavy task into a repeatable calculation.
• Structured data extraction: The workflow's input checklist (employment dates, travel logs, salary components) gives agents a clear schema to pull from HR systems or PDFs.

Practical scenarios

Cross-border secondment planning

An agent analyzes a U.S. engineer moving to China for 200 days. It flags that the 183-day threshold is met, identifies the U.S.-China treaty's 183-day exception under Article 15, and notes the six-year rule won't apply because this is the first year—automatically drafting a payroll instruction for the employer to stop withholding U.S. tax.

Social security exemption filing

For a Japanese employee being seconded for 36 months, the agent checks the Japan-China agreement (covered by the skill's list) and verifies the duration is within the 60-month cap. It generates a certificate request, lists the required supporting documents, and integrates with the employer's HR portal to send the application to the tax bureau.

Foreign tax credit reconciliation

After a Chinese resident working in Singapore files Singapore taxes, the agent calculates the foreign tax credit limit using the Chinese IIT progressive rates, contrasts with the Singapore rate, and prepares the Form 1050 (or equivalent) filing steps—including adjusting for any excess credit carryforward per the tax law.

Add it to your agent workflow

Install it directly:

npx skills add guoliang1114-boop/AriaAI --skill expatriate-tax-planning

Then, in your agent's system prompt or tool registry, reference the skill's domain (tax) and keywords. A minimal usage example:

# After installation, the skill's workflow is available as a tool
result = agent.run_skill("expatriate-tax-planning", {
  "employee_country": "Germany",
  "assignment_days": 540,
  "salary_base": "motherland",
  "social_security_country": "Germany"
})
print(result.residency_status)  # non-resident based on 183-day count

For broader context, you can browse the skill's details at OpenAgentSkill.

Compare before adopting

Before you build with this skill, compare it against alternatives: Verify the author's update history (last updated 2026-08-26) and the 37 GitHub stars signal community trust. Check whether the skill's tools abstract external APIs (e.g., China tax bureau database) or assume manual data entry—that affects agent autonomy. Also consider the workflow fit: if your team handles only domestic payroll, this skill's global focus adds overhead; but if you have frequent secondments, the built-in treaty logic saves you weeks of legal research.

Why it is worth tracking

Track this skill because cross-border tax rules rarely stay static—China's six-year rule and bilateral agreements shift annually. The skill's stable version tag and last-updated timestamp make it a reliable baseline, but you should re-evaluate after major tax law changes. Its 37 stars and single author suggest a niche but focused community; if you rely on it, watch for forks that might add missing treaties or integrate with commercial tax APIs. For now, it's a solid, well-structured choice for any agent handling expatriate compensation.