> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnao.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Skills
> Six published nao skills that automate the context-engineering lifecycle inside Claude Code, Codex, Cursor, or any agent that loads SKILL.md files
## What these skills are
nao publishes six **context-engineering skills** — standard `SKILL.md` files (YAML frontmatter + markdown) that any agentic CLI (Claude Code, Codex, Cursor, the Claude Agent SDK, …) can load and invoke.
Each skill is a self-contained workflow that automates one stage of the [Context Engineering lifecycle](/nao-agent/context-engineering/playbook): scoping a project, writing rules, building a test suite, auditing what's there, adding a semantic layer once tests show metric gaps, and deploying context to production via CI.
These skills are **for the human/agent driving nao** (in their IDE or terminal). They are different from the runtime skills the chat agent calls at query time — see [Tools, MCPs, Skills](/nao-agent/chat/capabilities/tools-mcps-skills) for those.
## Demo
## Install
The published source of truth lives at [github.com/getnao/nao/tree/main/skills](https://github.com/getnao/nao/tree/main/skills). Install all five into the current project's `.claude/skills/` with:
```bash theme={null}
nao skills add getnao/nao
```
`nao skills` is a thin wrapper around the [open-source `skills` CLI from Vercel Labs](https://github.com/vercel-labs/skills), so the equivalent direct call also works:
```bash theme={null}
npx skills add getnao/nao
```
Run from the root of the project where `nao_config.yaml` lives. Re-run any time to pick up updates; pass through `--force` to overwrite local edits.
Once installed, the skills are auto-discovered by Claude Code, Codex, and other agentic CLIs that load `.claude/skills/`. Trigger one by name (e.g. "use the setup-context skill") or let the agent route on the skill description.
## The six skills
### setup-context
Takes the user from `pip install nao-core` to a synced project with a starter `RULES.md`. **First-time install only** — for editing rules, generating tests, or reviewing an existing context, use the other skills below.
**Steps**
1. **Ask everything in one round** — warehouse + auth, scope (which tables, ≤100 with 20 as the target), extra context (dbt / ETL / BI repos, Notion, internal docs), LLM provider.
2. **Look up the warehouse-specific config** from [docs.getnao.io/nao-agent/context-builder/databases](/nao-agent/context-builder/databases), write `nao_config.yaml`, run `nao init`, then print a summary for the user to confirm before continuing.
3. **`nao sync`** — populate `databases/`, `repos/`, `docs/`, `semantics/`. Don't move on until sync is clean.
4. **Generate `RULES.md`** by handing off to `write-context-rules`.
5. **Wire up the LLM key** via `${ANTHROPIC_API_KEY}` (or equivalent) — never paste keys into chat.
6. **Recommend next steps** — smoke test with `nao chat`, review `RULES.md`, then `create-context-tests`.
### write-context-rules
Owns `RULES.md`. Generates the six standard sections, section by section, showing the user each block before moving on. If `RULES.md` already has content, runs an audit-and-fill flow that fills only what's missing.
**Steps**
1. **`## Business overview`** — Product + Business model (sourced from web search + `databases/` + dbt repo).
2. **`## Data architecture`** — Warehouse, data stack, layers, sources.
3. **`## Core data models`** — `### Most Used Tables` (one-line pointers) + `### Tables detail` (Purpose, Granularity, Key Columns ≤10, Use For).
4. **`## Key Metrics Reference`** — grouped by category; `**metric** → table, column, formula`.
5. **`## Date filtering`** — three example formulas (last X weeks / last X days / current month) keyed off the user's week-boundary and current-period-inclusion conventions.
6. **`## Analysis Process`** — five subsections: Understand → Select Table → Write Query → Validate → Context.
7. **Validate metrics with the user** — confirm every source-of-truth pointer in the metrics reference.
8. **Date filtering, with the user** — pick week boundary (Sunday vs Monday) and current-period inclusion.
**Template** — [`templates/RULES.md`](https://github.com/getnao/nao/blob/main/skills/write-context-rules/templates/RULES.md), the six-section scaffold:
````markdown theme={null}
# RULES.md
> Included with every message sent to the nao agent. Keep it lean.
> Per-table detail belongs in `databases/
.md`, not here.
## Business overview
**Product**: …
**Business model**: …
## Data architecture
**Warehouse:** …
**Data stack:** …
**Data layers:** …
**Data sources:** …
## Core data models
### Most Used Tables
- `
.`, ``
## Date filtering
> Convention: e.g. "Week starts Monday; 'last X weeks' excludes the current incomplete week."
### Last X weeks
```sql
…
```
### Last X days
### Current month
## Analysis Process
### 1. Understand the Question
### 2. Select the Right Table(s)
### 3. Write Efficient Queries
### 4. Validate Results
### 5. Provide Context
````
### create-context-tests
Generates a test suite of natural-language → SQL pairs that becomes the reliability benchmark. `nao test` runs each prompt through the agent, executes both the agent's SQL and the test's expected SQL, and **diffs the result data row-by-row**. See [Evaluation](/nao-agent/context-engineering/evaluation) for the scoring model.
**Two authoring rules**
* **Prompts read like real chat.** Short, vague, no table / column / method hints. `"How's churn looking this quarter?"`, not `"What was the churn rate from fct_subscriptions in Q1?"`.
* **Output column names encode format / unit, not source.** `churn_rate_float_0_1`, not `churn_rate_from_fct_subscriptions`.
**Steps**
1. **Ask once** — does the user have trusted source-of-truth queries (Looker, dashboards, prior benchmarks)? Transform each into a test; for metrics without a trusted query, draft new ones.
2. **Save flat under `tests/`** (no subfolders), one YAML file per test.
3. **Have the user validate** — prompts match their team's phrasing, SQL matches their definition of truth.
4. **Run `nao test -m -t 10`** — recap pass rate, token cost, wall-clock time as the baseline.
5. **Diagnose failures** — read `tests/outputs/`, identify the rule gap, route to `write-context-rules` for the smallest fix. Re-run between fixes so impact is attributable.
**Template** — [`templates/test.yaml`](https://github.com/getnao/nao/blob/main/skills/create-context-tests/templates/test.yaml):
```yaml theme={null}
name: churn_rate_last_quarter
prompt: How's churn looking this quarter?
sql: |
SELECT
SAFE_DIVIDE(churned, total) AS churn_rate_float_0_1
FROM (
SELECT
COUNTIF(churned_at IS NOT NULL) AS churned,
COUNT(*) AS total
FROM ..fct_subscriptions
WHERE started_at < DATE_TRUNC(CURRENT_DATE, QUARTER)
);
# Optional:
# category: revenue | activity | conversion | churn | retention | …
# difficulty: easy | medium | hard
# notes: why this test matters / what failure mode it catches
```
### audit-context
Diagnoses a nao context. Finds gaps, MECE violations, failure root causes, and bloat. Output is a short in-conversation report ending in a prioritized plan. **Diagnose only — never fixes.** Routes fixes to `write-context-rules` / `add-semantic-layer` / `create-context-tests`. Run any time: right after `setup-context`, mid-build, before a release, or when behavior gets surprising.
**Steps — six checks in order**
1. **Synced context** — what's wired in (warehouse, repos, Notion, semantic layer, MCPs) vs missing. Has `nao sync` run? Scope check: ≤100 tables hard ceiling, ≤20 ideal. Oversized scope is the biggest predictor of reliability failure — flag it explicitly.
2. **`RULES.md` vs target structure** — six sections from `write-context-rules`. Per section, mark **present / missing / thin**. Flag placeholders, `TODO:` markers, and metric entries with no source-of-truth pointer.
3. **Per-table coverage** — every table in `databases/`: is it in `## Most Used Tables`? Has a `## Tables detail` block? dbt context (`schema.yml`)? Per-table gaps: undocumented columns, calculated fields with no explanation, foreign keys with no relation.
4. **Data model consistency (MECE)** — two tables computing the same metric differently? Asked metrics no in-scope table can answer? Duplicated columns under different names? Ambiguous columns (`amount` without unit, `status` without enum values)?
5. **Test coverage** — if `tests/` is empty, recommend `create-context-tests`. Otherwise read `tests/outputs/` and categorize each failure (data model / date selection / test issue / interpretation / metric definition) with the smallest rule change per failure.
6. **Token optimization** — files >40KB, `## Tables detail` blocks past the 10-column cap, duplication between `RULES.md` and `databases/
.md`, in-scope tables with no mention in any test.
**Output**
Lead with a one-paragraph summary (`sync state | scope wideness | rules quality (N/6 sections substantive) | test coverage`), deep-dive only sections with findings, end with a prioritized plan that names the skill that does each fix:
```
## Plan
1. (easy / 5 min) … → write-context-rules
2. (small / 30 min) … → create-context-tests
3. (medium / 1-2 hr) … → audit-context (rerun after)
4. (large / multi-session) … → add-semantic-layer
```
### add-semantic-layer
Wires a semantic layer into the agent so metric queries go through a single canonical definition. **Only after `nao test` shows metric-reliability failures** — not before. A semantic layer reduces the scope of answerable questions; the trade-off only pays off when reliability is the bottleneck. Schema gaps or date logic failures are rule-fixes, not semantic-layer fixes.
**Steps**
1. **Pick the tool**
| Option | Type | When |
| ------------------------------ | -------------- | ---------------------------------------------------------- |
| **dbt MetricFlow** | Metric store | Already running dbt Cloud with the Semantic Layer enabled. |
| **Snowflake views / semantic** | Semantic layer | Snowflake; using curated views or native semantic views. |
| **nao semantic files** | Semantic layer | No existing layer. Want a lightweight in-repo YAML. |
| **Other** (Looker, Cube, …) | Varies | Search the MCP registry; otherwise fall back to nao YAML. |
2. **Install the matching MCP** under `.claude/mcp.json` (dbt-mcp / mcp-server-snowflake / Cortex MCP, etc.). Credentials via `${ENV_VAR}` only — never inline.
3. **Hand off to `write-context-rules`** to route every metric in `## Key Metrics Reference` through the new layer (e.g. `MRR → query via dbt MCP query_metric (semantic layer)`).
4. **Validate** — `nao chat` one of the user's top questions, confirm the agent uses the semantic layer, then `nao test` and **compare to the pre-semantic-layer baseline pass rate**. Reliability is the only reason to do this — measure it.
**Template — nao YAML option** ([`templates/semantic.yaml`](https://github.com/getnao/nao/blob/main/skills/add-semantic-layer/templates/semantic.yaml)):
```yaml theme={null}
dimensions:
- name: date
type: date
description: Calendar date. Use this for any time-based slicing.
- name: plan
type: categorical
description: Subscription plan tier.
values: [free, pro, enterprise]
metrics:
- name: mrr
definition: Monthly Recurring Revenue from active paying subscriptions, in USD.
source:
table: fct_stripe_mrr
column: mrr_amount
aggregation: SUM # SUM | COUNT | COUNT_DISTINCT | AVG | MIN | MAX
grain: month # day | week | month | quarter | year
dimensions: [date, plan, country]
filters:
- "status = 'active'"
```
For the dbt MetricFlow / Snowflake / Cortex paths, the metric definitions live upstream — this skill installs the MCP and routes `RULES.md` to it instead of writing local YAML.
### deploy-context
Wires a GitHub Actions workflow that runs `nao deploy` on every push to `main`, so context changes go live automatically. Handles API key creation, GitHub Secrets setup, `.naoignore` hardening, and the workflow file itself.
**Steps**
1. **Prerequisites check** — remote URL, repo, `project_name`, confirm who can mint an API key.
2. **API key creation** — walk through Settings -> Organization -> API Keys. The key is shown once; store it as a GitHub Secret, never in the workflow or `nao_config.yaml`.
3. **GitHub Secrets** — `NAO_URL` and `NAO_API_KEY`, plus optional warehouse/Notion secrets if the user also wants `nao sync` in CI. For multi-environment teams, use GitHub Environments.
4. **`.naoignore` hardening** — review the always-excluded set (`.git`, `.venv`, `.env`, `node_modules`, `__pycache__`, `repos`, `*.pyc`) and add project-specific patterns.
5. **Workflow file** — `.github/workflows/nao-deploy.yml` with `on: push: branches: [main]`, `workflow_dispatch`, concurrency serialization, and the API key passed via `env:` (never a CLI literal).
6. **Optional `nao sync` step** — most teams keep sync on a cron and let its commit trigger the deploy workflow.
7. **End-to-end verification** — trigger a push, watch for the success message, confirm the remote project matches `main`.
**Guardrails**: never commit secrets; one API key per repo/environment; no `pull_request` trigger (forks could exfiltrate the key); every deploy is a full replacement.
## When to use which
```
setup-context → write-context-rules → create-context-tests → audit-context (anytime)
(first time only) (any rules change) (benchmark + extend) (diagnose, never fix)
│
▼
tests reveal metric
reliability gaps?
│
▼
add-semantic-layer
(then back to write-context-rules)
Ready to ship?
│
▼
deploy-context
(CI/CD to production)
```
| If you want to… | Use |
| -------------------------------------------------------------- | ------------------------------------------------------------- |
| Set up nao on a brand-new project | `setup-context` |
| Generate or rewrite `RULES.md` | `write-context-rules` |
| Add tests for a new metric, or build the first benchmark | `create-context-tests` |
| Find out what's missing, broken, or bloated | `audit-context` |
| Make metric calculations consistent across questions | `add-semantic-layer` (only after tests show the gap) |
| Refine `RULES.md` because the agent keeps making the same miss | `write-context-rules` (preceded by `audit-context` if unsure) |
| Auto-deploy context to production on every push | `deploy-context` |
## Source material
The skills are distilled from the public Context Engineering content:
* [Playbook](/nao-agent/context-engineering/playbook)
* [Principles](/nao-agent/context-engineering/principles)
* [RULES.md](/nao-agent/context-builder/rules-context)
* [Evaluation](/nao-agent/context-engineering/evaluation)
Read each skill's source `SKILL.md` in the repo: [github.com/getnao/nao/tree/main/skills](https://github.com/getnao/nao/tree/main/skills).