Agent Skills
A skill is a SKILL.md file an AI agent installs once and reads when a task matches: what the Maison tools do, which one to call for which intent, the order that works, the inputs, and the mistakes to avoid. Maison publishes one skill per tool group plus an umbrella skill, generated from the same OpenAPI document that drives the API, the MCP server and the A2A endpoint — so they are always current. The format follows the Agent Skills specification.
Why skills, when the API is already self-describing?
The OpenAPI document, MCP tools/list and the A2A agent card tell an agent what exists. They cannot say when to use create_client instead of five smaller calls, that an answer must be re-tested in a new session after a knowledge change, that update_translations replaces the whole map, or that a 403 listing missing grants means stop rather than retry. Without that, agents guess: they chain low-level calls, retry refused tools, send the wrong field names, and burn tokens reading 228 schemas to find one.
- Fewer, better calls. Each skill names the one-shot tool for an intent and the workflow order, so the first call is usually the right one.
- Progressive disclosure. The agent loads about 100 tokens of metadata per skill at startup, the full skill only when the task matches, and the per-tool reference only when it needs exact fields — instead of the whole catalogue every turn.
- Permission-aware. Skills explain the all-or-nothing grant model, the plan entitlements and the composite fallbacks, so refusals are handled in one sentence.
- Transport-neutral. One skill covers REST, MCP and A2A with the same tool names and exact request shapes, whichever your runtime speaks.
Install
Any agent runtime that supports Agent Skills can install from this site. With the skills CLI (Claude Code, Cursor, Codex, Copilot and others):
npx skills add https://docs.maison-labs.com
# one skill only
npx skills add https://docs.maison-labs.com --skill maison-knowledgeOr copy a skill by hand into your agent's skills directory:
mkdir -p .claude/skills/maison-public-api && curl -fsSL https://docs.maison-labs.com/skills/maison-public-api/SKILL.md -o .claude/skills/maison-public-api/SKILL.mdDiscovery endpoints for tools that look for skills automatically: /skill.md, /.well-known/agent-skills/index.json, /llms.txt. The API itself is at https://maison-labs.com/api/v1 (API key in x-api-key; see Authentication).