If you are building agents for financial compliance, corporate due diligence, or KYC workflows, you have probably hit the same wall: the model can talk about companies, but getting official registry data — directors, beneficial owners, filings, etc. means custom API glue, brittle prompts, and hope that the LLM picked the right legal entity.
ARPA’s latest addition to the Skillware registry — finance/uk_companies_house_handler — lets any supported model or agent query the UK Companies House Public Data API through structured tool calls. Natural language stays with the agent, HTTP, parsing, disambiguation, and UK corporate terminology stay in deterministic Python. Shipped in Skillware v0.4.1, authored by @Areen-09.
Ask “Who is the CEO of BP?” and the agent maps intent, resolves the company, fetches officers, without inventing a company number or confusing US job titles with UK registry roles.
Skillware in a nutshell
Skillware is an open-source framework for installable agent capabilities. Each skill is a bundle:
-
skill.py— deterministicexecute()returning JSON -
instructions.md— when and how the model should call the tool -
manifest.yaml— schema, constitution, issuer, env vars - Tests and catalog docs — shipped in the wheel
You load_skill("category/skill_name"), adapt for Gemini, Claude, OpenAI, or others, pass instructions as system context, and wire tool calls to execute(). Same loop everywhere — see the introduction and agent loops guide.
That split is why agents prefer it over ad-hoc tool JSON or opaque skills blobs: the model decides when; the skill decides how, predictably, every time. No LLM inside the handler. No mystery middleware. One registry ID, any runtime.
uk_companies_house_handler: what it does
Registry ID: finance/uk_companies_house_handler
Catalog: uk_companies_house_handler.md
Six actions, one entry point:
| Action | Purpose |
|---|---|
map_intent |
Turn keywords like “CEO”, “owner”, “shareholder” into the right UK operations |
resolve_company |
Search by name; return ranked candidates or a single match |
get_company_profile |
Status, type, SIC codes, address, charges, insolvency flags |
get_officers |
Directors and secretaries (current or historical) |
get_pscs |
Persons with significant control — UK beneficial ownership |
get_filing_history |
Accounts, confirmation statements, incorporations |
Every response carries a status envelope: ready, needs_input, or error, plus fetched_at and source. Ambiguous names like “BP” return candidates, not guesses — the agent asks the user, then continues with a verified company_number.
Bundled terminology_map.yaml translates US business language into UK registry concepts (CEO → director, owner → PSC). The constitution is explicit: public data only, no filing submissions, no caching officer PII beyond the request, always cite company number and timestamp.
Setup: a free Companies House API key in .env as COMPANIES_HOUSE_API_KEY. Provider keys (e.g. GOOGLE_API_KEY) only if you run an LLM loop.
Agent vs skill
| Agent (LLM + your loop) | Skill |
|---|---|
| Parses natural language | Executes HTTP against Companies House |
| Handles disambiguation dialogue | Returns structured candidates and next actions |
| Synthesizes the final answer | Maps intent keywords to operations |
The skill does not replace your compliance analyst — it equips the agent with the same structured lookups an analyst would run, at machine speed, auditable step by step.
Try it: direct execute
from skillware.core.loader import SkillLoader
from skillware.core.env import load_env_file
load_env_file()
bundle = SkillLoader.load_skill("finance/uk_companies_house_handler")
skill = bundle["class"]()
result = skill.execute({"action": "resolve_company", "query": "BP", "limit": 5})
print(result["status"], result.get("candidates"))
Try it: intent → officers pipeline
intent = skill.execute({
"action": "map_intent",
"intent_keywords": "CEO, director",
"entities": {"company_query": "BP"},
})
officers = skill.execute({
"action": "get_officers",
"company_number": "00102498",
"active_only": True,
})
Try it: full Gemini loop
Runnable scripts ship in the repo:
pip install -U skillware
python examples/uk_companies_house_handler_demo.py
python examples/gemini_uk_companies_house_handler.py
The demo script is mocked (no API key). The Gemini example needs GOOGLE_API_KEY and COMPANIES_HOUSE_API_KEY.
Outro
Government registries are not chat-native. They are API-native, jurisdiction-specific, and unforgiving about entity resolution. finance/uk_companies_house_handler turns that into a plug-and-play Skillware bundle: load once, chain with screening or token-budget skills, run on any model you already use.
Links
Questions and skill ideas welcome in the repo. If your agents touch UK corporates, start here — before the model freelances a company number.
Top comments (0)