From hex-context-best-practices
Use this skill whenever someone is setting up, improving, or planning a rollout of agentic analytics in Hex — especially Threads, the Notebook Agent, or the Modeling Agent. Triggers on: "context strategy", "context engineering", "set up Threads", "workspace guide", "warehouse descriptions", "endorse tables", "semantic model", "my agent gave the wrong answer", "roll out self-service analytics", "how do I make Hex AI more accurate", "Hex Context Studio". Always use this skill for any task about making Hex's agents trustworthy or scaling them to business users — even if the request is phrased casually like "help me get my data team using AI" or "why does Threads keep picking the wrong table". This skill both advises on strategy AND drafts the actual context assets (workspace guides, descriptions, semantic models) and rollout plans.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hex-context-best-practices:hex-context-best-practicesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Help a data team build a **context strategy** for Hex's agents and roll it out so business users can
Help a data team build a context strategy for Hex's agents and roll it out so business users can self-serve trustworthy answers. This skill does two jobs: (1) advise on and draft the four context assets, and (2) produce a phased rollout plan tailored to the team's situation.
The single most important idea: agents are only as good as the context you give them, and context compounds. It does not need to be perfect on day one. Start with what exists, scope to one use case, and improve every loop.
This skill has two specialists. Figure out which the person needs and route accordingly. They will often need both, usually in this order: build context first, then plan the rollout.
| If the person wants to… | Use |
|---|---|
| Decide what context to build, write workspace guides / descriptions / semantic models, or fix a wrong agent answer | agents/context-architect.md |
| Plan how to introduce Threads to their team and scale it in phases | agents/rollout-planner.md |
Spawning the specialist:
agents/ as a subagent.agents/ file inline
and follow it. The files are written to work either way.Before doing detailed work, gather context about their setup. Both specialists lean on
references/intake.md — a short questionnaire the person can answer (or attach docs to) so the
output fits their actual warehouse, team, and use case. Don't interrogate; ask for what you need,
infer the rest, and note assumptions.
Keep steps current. Hex's UI changes. Before giving step-by-step instructions, fetch the relevant
page from references/hex-docs.md so the steps are accurate.
Hex's agents reference four categories of context. Each has one job. The skill of keeping each category focused on its job is context engineering. The categories sit on a spectrum from loose guidance to rigid governance:
Advanced sources (optional, later-stage): on Team/Enterprise, two more sources extend the four —
reference repositories (connect GitHub/GitLab so the agent reasons over your code: metric logic,
table structures, event logging) and External Apps / MCP (let the agent use Notion, Linear, or
custom MCP tools). Surface these only when the person asks about code repos or MCP, already has repos
connected to their AI tooling, or has matured past the basics. They're governed the same way as the
core four — by a clear description. See references/advanced-context.md.
The routing rule that keeps categories clean (state this whenever someone is unsure where a piece of context belongs):
Where ownership tends to land: warehouse descriptions and semantic models live closer to the warehouse (analytics engineering); endorsements and workspace guides live closer to Hex's UI (analysts/admins). There's no hard rule.
Observability closes the loop. Context can't improve without visibility. Hex's Context Studio
shows usage/adoption, lets you manage assets, surfaces trending questions and agent responses, and —
via Suggestions — auto-generates concrete context fixes from conversation patterns and feedback.
To find what to improve, ask Hex itself (the agent knows your warehouse and context); see
references/ask-hex.md for in-product, MCP, and CLI ways to do that. Improvement is never "done" —
frequent at first, tapering over time.
Prioritization (the 30-minute start): endorse a few golden tables and exclude junk → add descriptions to the most-queried endorsed tables/columns → write a workspace guide with 5–10 rules → add semantic models to codify key metrics. Always scope to a real business use case. Don't boil the ocean.
customer_id in the customer schema"
works better than "don't use the wrong key."agents/context-architect.md — advise on + draft the four context assets; diagnose and fix wrong answers.agents/rollout-planner.md — produce a phased, customized rollout plan.references/intake.md — the questionnaire for customizing output to the person's setup.references/context-assets-deep-dive.md — detailed patterns and full examples (workspace guide,
semantic model YAML, the fix framework). Read when the architect needs depth.references/advanced-context.md — reference repositories (code) and External Apps / MCP. Read when
the person asks about repos or MCP, or already has code connected to their AI tooling.references/hex-docs.md — canonical Hex doc links. Fetch the relevant page before giving UI steps.references/ask-hex.md — tiered ways (in-product / MCP / CLI) to get Hex's own signal on what
context to improve, including the hex suggestion list CLI loop.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub hex-inc/hex-skills --plugin hex-context-best-practices