Cross Border Streamer Tax Legal Advisor Agent Skill

SKILL.md — Skill Registry (cross-border-streamer-tax-legal-advisor)

> Single source of truth for how skills are registered, resolved, executed, and validated in the runtime engine. Generated from the live SkillRegistry via scripts/generate_manifest.py; the machine-readable twin lives at assets/schemas/skill_manifest.json.

This skill ships two parallel, equivalent layers that share one deterministic backbone (tools/tax_data.py) and one knowledge base (SECOND-KNOWLEDGE-BRAIN.md):

| Layer | Purpose | Location | |-------|---------|----------| | Declarative (markdown) | Claude Code reasoning persona, prompts, gates | skills/*.md | | Runtime (registry) | Programmatic orchestration: registry, router, hooks, tools, engine | agent/ |

Both layers emit the same 6-step pipeline guarded by the same 10 quality gates (U1–U6 + G1–G4) and the same 4-verdict contract.

1. How a skill is registered

A skill is a subclass of agent.base.Skill exposing a frozen SkillManifest (name, description, version, step, input/output JSON schemas, the tools it may call, and its quality gate) and an execute(ctx, state) method. Registration goes through SkillRegistry:

from agent.skills import build_default_registry
reg = build_default_registry()        # default toolset + 6 skills
reg.register_tool(MyTool())           # add a custom tool
reg.register_skill(MySkill())         # add a custom skill (step-ordered)
reg.validate_manifests()              # every schema is well-formed

Registration invariants enforced by SkillRegistry:

• unique skill name and unique step index;
• every tool referenced in manifest.tools must already be registered;
• validate_manifests() checks each input/output schema is itself a valid JSON-Schema subset.

2. How a request is resolved

agent.router.ChainOfThoughtRouter.plan() inspects the request and returns an ordered execution plan (one entry per skill invocation):

• combined (default): the full 6-step pipeline in order;
• focused (residency / withholding / vat / deductions / ip): the same pipeline with the core step narrowed to the focus;
• comparison: runs sub-core-analysis once per case payload.

An unknown analysis_type degrades to combined with an explicit assumption recorded on RunState — the router never invents steps.

3. How a skill is executed

Skill.safe_execute(ctx, state) wraps execute with:

1. input validation against manifest.input_schema; on failure it records a limitation, escalates degradation to Level 3, and returns an error dict (never raises to the engine);
2. the execute call, which mutates RunState (limitations, degradation, retries, events) and returns an output dict;
3. output validation against manifest.output_schema; a schema mismatch is recorded as a limitation but the partial output is preserved.

Tool.safe_execute follows the same contract for individual tool calls, returning a ToolResult(ok, value, error, source).

4. How everything is validated

• Manifests: SkillRegistry.validate_manifests() — every skill's input/output schema is a well-formed JSON-Schema subset.
• I/O: agent.base.validate_instance — a dependency-free validator for type/required/properties/enum/items/additionalProperties/minimum/maximum/minItems/oneOf, applied on every tool and skill boundary.
• Project contract: tools/validate_project.py — the 8-File Contract + cross-file integrity + encoding + phase-tracker checks.
• Deterministic data: scripts/seed_tax_data.py — referential integrity of tax_data.py (treaty jurisdictions exist, rates in range, verdict set matches the contract).

5. Registered skills

| Step | Skill | Tools | Quality gate | |------|-------|-------|--------------| | 1 | sub-gather-requirements | languagedetect, jurisdictionslist | at least one object + residency jurisdiction confirmed | | 2 | sub-evidence-collector | residencylookup, withholdinglookup, vatlookup, platformlookup, form1099kthreshold, knowledgebrainquery | at least current data + 1 authoritative document, or limitat | | 3 | sub-core-analysis | residencylookup, withholdinglookup, vatlookup, platformlookup, deductionslist, ipriskslist | residency/PE assessed; withholding & treaty mapped; VAT addr | | 4 | sub-knowledge-updater | knowledgebrainquery, jurisdictionslist | at least 1 academic/authoritative source surfaced; coverage | | 5 | sub-advisor | knowledgebrainquery | conclusion is exactly one declared verdict; disclosure prece | | 6 | quality-gate | — | all gates pass or carry an explicit limitation notice |

sub-gather-requirements (step 1)

Clarify object, constraints, timeframe, inputs, audience, language. · version 2.0.0

Input schema:

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string"
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "resident_jurisdiction": {
      "type": "string"
    },
    "source_jurisdictions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "income_usd": {
      "type": [
        "number",
        "null"
      ]
    },
    "days_present": {
      "type": [
        "integer",
        "null"
      ]
    },
    "year": {
      "type": "integer"
    },
    "language": {
      "type": "string",
      "enum": [
        "en",
        "vi"
      ]
    },
    "analysis_type": {
      "type": "string"
    }
  }
}

Output schema:

{
  "type": "object",
  "required": [
    "requirements",
    "assumptions",
    "missing_decisive"
  ],
  "properties": {
    "requirements": {
      "type": "object"
    },
    "assumptions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "missing_decisive": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

sub-evidence-collector (step 2)

Fetch authoritative real-time + reference data with tier labels. · version 2.0.0

Input schema:

{
  "type": "object",
  "required": [
    "upstream"
  ],
  "properties": {
    "upstream": {
      "type": "object"
    }
  }
}

Output schema:

{
  "type": "object",
  "required": [
    "evidence",
    "degradation_level"
  ],
  "properties": {
    "evidence": {
      "type": "object",
      "required": [
        "current_data",
        "authoritative_docs",
        "recent_news",
        "reference_benchmarks"
      ],
      "properties": {
        "current_data": {
          "type": "array"
        },
        "authoritative_docs": {
          "type": "array"
        },
        "recent_news": {
          "type": "array"
        },
        "reference_benchmarks": {
          "type": "array"
        }
      }
    },
    "degradation_level": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4
    },
    "substituted_sources": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

sub-core-analysis (step 3)

Residency/PE, withholding & treaty, VAT/GST, deductions, IP, scenarios. · version 2.0.0

Input schema:

{
  "type": "object",
  "required": [
    "upstream"
  ],
  "properties": {
    "upstream": {
      "type": "object"
    },
    "analysis_type": {
      "type": "string"
    },
    "comparison_case": {
      "type": "object"
    },
    "case_index": {
      "type": "integer"
    }
  }
}

Output schema:

{
  "type": "object",
  "required": [
    "income_inventory",
    "residency",
    "withholding",
    "vat",
    "deductions",
    "ip_risks",
    "scenarios"
  ],
  "properties": {
    "income_inventory": {
      "type": "array"
    },
    "residency": {
      "type": "object"
    },
    "withholding": {
      "type": "array"
    },
    "vat": {
      "type": "array"
    },
    "deductions": {
      "type": "array"
    },
    "ip_risks": {
      "type": "array"
    },
    "scenarios": {
      "type": "array"
    }
  }
}

sub-knowledge-updater (step 4)

Query the knowledge base; surface citations; flag crawl gaps. · version 2.0.0

Input schema:

{
  "type": "object",
  "required": [
    "upstream"
  ],
  "properties": {
    "upstream": {
      "type": "object"
    }
  }
}

Output schema:

{
  "type": "object",
  "required": [
    "citations",
    "gaps",
    "coverage"
  ],
  "properties": {
    "citations": {
      "type": "array"
    },
    "gaps": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "coverage": {
      "type": "string",
      "enum": [
        "Strong",
        "Moderate",
        "Weak"
      ]
    }
  }
}

sub-advisor (step 5)

Synthesize a risk-disclosed verdict with evidence chain + remediation. · version 2.0.0

Input schema:

{
  "type": "object",
  "required": [
    "upstream"
  ],
  "properties": {
    "upstream": {
      "type": "object"
    }
  }
}

Output schema:

{
  "type": "object",
  "required": [
    "verdict",
    "scenarios",
    "key_risks",
    "evidence_chain",
    "remediation",
    "disclosure"
  ],
  "properties": {
    "verdict": {
      "type": "string",
      "enum": [
        "Compliant Plan",
        "Conditional (documentation)",
        "Compliance Risk",
        "Inconclusive"
      ]
    },
    "scenarios": {
      "type": "array"
    },
    "key_risks": {
      "type": "array"
    },
    "evidence_chain": {
      "type": "array"
    },
    "remediation": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "disclosure": {
      "type": "string"
    }
  }
}

quality-gate (step 6)

Enforce U1-U6 + G1-G4 gates with auto-fix + 2-retry enforcement. · version 2.0.0

Input schema:

{
  "type": "object",
  "required": [
    "upstream"
  ],
  "properties": {
    "upstream": {
      "type": "object"
    }
  }
}

Output schema:

{
  "type": "object",
  "required": [
    "gates",
    "limitations",
    "degradation_level"
  ],
  "properties": {
    "gates": {
      "type": "object"
    },
    "limitations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "degradation_level": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4
    }
  }
}

6. Registered tools

| Tool | Description | |------|-------------| | residency_lookup | Assess tax residency for a jurisdiction via the statutory day-count test. | | withholding_lookup | Compute effective withholding (default + treaty-capped) for a source->resident pair. | | vat_lookup | Return the VAT/GST rule for a jurisdiction (rate, threshold, mechanism). | | platform_lookup | Return the platform rule (payout share, reporting regime, WHT notes). | | form_1099k_threshold | Return the US Form 1099-K (gross, transactions) threshold for a tax year. | | deductions_list | List deductible expense categories with typical deductibility + caveats. | | ip_risks_list | List IP/contract cross-border risk checklist with mitigations. | | jurisdictions_list | List all jurisdictions covered by tax_data. | | knowledge_brain_query | Query the knowledge brain for citations matching keywords/jurisdictions; flag gaps. | | language_detect | Detect whether the query is Vietnamese or English. |

Every tool's full input/output JSON schema is written to assets/schemas/tool_.schema.json by scripts/generate_manifest.py.

7. Quality gates & verdicts

Universal gates U1–U6: ≥3 cited sources (≥1 Tier 1–2); disclosure before the recommendation; tier labels on every source; language matches the request; the declared template; every claim traceable to a source or [analyst judgment].

Domain gates G1–G4: residency/PE assessed; withholding & treaty relief mapped per source→resident pair; VAT/GST addressed per jurisdiction; disclaimer present.

Enforcement: apply each gate in order; on failure run the auto-fix; after 2 failed retries emit an explicit limitation notice and continue. Never silently pass a gate.

Verdict contract (exactly one per run): Compliant Plan / Conditional (documentation) / Compliance Risk / Inconclusive.

8. Hooks & lifecycle

agent.hooks.HookManager dispatches lifecycle phases to every registered Hook (isolating failures). Built-in hooks: LoggingHook (error + run summary), StateMetricsHook (per-step metrics). EventEmitter records structured Events on RunState and forwards them to hooks. Phases: on_start, on_step_pre, on_step_post, on_gate, on_event, on_error, on_complete.

9. Configuration & feature flags

Type-safe configuration lives in config/ (config/settings.py + config/default.toml). Precedence: compiled defaults SKILL.md is regenerated from the live registry; edit the registry (agent/skills/*) and re-run the generator rather than hand-editing the tables below this line.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/cross-border-streamer-tax-legal-advisor-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.