Skip to content
Skills Library
Data & analytics · Tool integration

setup-amql-development

/setup-amql-development

Use this whenever working in a (Holistics) AMQL project (i.e. with AML files). It guides you to set up and review the AMQL development environment and tooling so that the development can be done accurately and efficiently. Tooling includes CLI, MCP, code synchronization, etc.

Repository
skills ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use this whenever working in a (Holistics) AMQL project (i.e. with AML files). It guides you to set up and review the AMQL development environment and tooling so that the development can be done accurately and efficiently. Tooling includes CLI, MCP, code synchronization, etc.

Original author description

Use this whenever working in a (Holistics) AMQL project (i.e. with AML files). It guides you to set up and review the AMQL development environment and tooling so that the development can be done accurately and efficiently. Tooling includes CLI, MCP, code synchronization, etc.

How it works

  1. Mandatory preparation steps
  2. Anchor this skill set in the project's CLAUDE.md
  3. AQL & Viz authoring mode
  4. Holistics CLI
  5. Calling tools via the CLI
Original SKILL.md headings · 74 lines, 849 words
SKILL.md preview
---
name: setup-amql-development
description: "Use this whenever working in a (Holistics) AMQL project (i.e. with AML files). It guides you to set up and review the AMQL development environment and tooling so that the development can be done accurately and efficiently. Tooling includes CLI, MCP, code synchronization, etc."
---

# Setup AMQL development
* Holistics Development environment is where the user develops their analytics as-code (AMQL), including modeling, metrics, dashboards, etc. before publishing them to the Reporting environment to provide analytics to end-users.

## Mandatory preparation steps
* **ALWAYS** read [](../../references/holistics.md), and other references if necessary, to understand the Holistics and AMQL context properly. Your knowledge and assumptions about Holistics and AMQL are likely inaccurate or outdated.
* Use [](../develop-amql/) skill when working with AMQL codes.
* Set up Holistics CLI to use powerful Holistics tools and make your development faster, more efficient, and more accurate.

## Anchor this skill set in the project's CLAUDE.md
Skill discovery isn't always reliable across sessions. To make future sessions reliably pick up the right Holistics skills in this project, check the project root for a `CLAUDE.md` and ensure it mentions Holistics AMQL and lists the key skills. If missing, propose this snippet to the user and ask before writing:

````md
## Holistics AMQL
This project uses Holistics AMQL - a domain-specific language for analytics-as-code (`.aml` files), with its own syntax for models, datasets, dashboards, and metrics, plus AQL for querying. Your training data on AML, AQL, and the Holistics platform is likely outdated or wrong; working from memory will produce broken code. **Always** load the `holistics-development` plugin skills before writing AML/AQL or answering Holistics questions:

- `holistics-development:setup-amql-development` - start here; environment, CLI, MCP setup
- `holistics-development:develop-amql` - writing models, datasets, dashboards, metrics
- `holistics-development:write-aql` - querying datasets via AQL
- ...and others (e.g. `search-docs`, `analyze-data`, `visualize-data`) - browse the `holistics-development` plugin's skill list

If you catch yourself guessing at AML syntax or Holistics behavior, load the relevant skill instead.
````

Don't duplicate if equivalent pointers already exist.

## AQL & Viz authoring mode
AQL and Viz are written in one of two modes:
- **`holistics-ai`** (default) — Holistics AI writes AQL and Viz (`generate_aql`, `generate_viz`).
- **`self`** — the agent writes AQL and Viz itself from the bundled `aql` / `viz` skill references, and validates them with `validate_aql` / `execute_viz`.

If the project's instructions don't already state a mode, ask the user once which one they want (don't change it unprompted), then record it:
- **For this project** (any agent tool): add `Holistics authoring mode: self` (or `holistics-ai`) to the project's `CLAUDE.md` / `AGENTS.md`.
- **For this user** (Claude Code): `/plugin configure holistics-development@holistics-skills` and set *AQL & Viz authoring*.

The project's instructions take precedence over the plugin setting.

## Holistics CLI
### Setup (once)
Use [](../setup-holistics-cli/) skill

### Usage
* Use `holistics sync-code --background` to synchronize local codes with Holistics backend, enabling and making sure tools run on latest codes
  * Conflicts (with conflict markers) are normal. Resolve them in place — do **not** stop `sync-code --background` to resolve them; your local fix syncs to cloud, and stopping/restarting just re-triggers the conflict in a loop.
* Use `holistics aml validate <files...>` to validate AML files after making every new change. For example:
  * `holistics aml validate "new file.model.aml" "new_file2.dataset.aml"`
  * `holistics aml validate **/*.aml`
* Use `holistics mcp` to call Holistics tools — see *Calling tools via the CLI* below.

## Calling tools via the CLI
Skills refer to Holistics tools by name with JSON parameters (e.g. tool `execute_aql` with `{ "dataset_uname": ..., "aql": ... }`). Without a direct MCP connection, call them through the CLI:

* `holistics mcp` — list the tools.
* `holistics mcp <tool> --help` — the tool's input schema (property names, which are required).
* `holistics mcp <tool> '<json>'` or JSON on stdin — call it.

**Parameters are ONE JSON object** — never `key=value` arguments or flags (`holistics mcp execute_aql dataset_uname=x ...` fails with "too many arguments").

**Never guess parameter names or skip required ones.** A wrong key (e.g. `query` instead of `question` for `search_docs`) or a missing required one (e.g. `refresh_cache` for `execute_aql`) fails the whole call. Before the first call of a tool in a session, read its `--help` and use exactly the documented property names.

**Pass AQL / AML payloads through a JSON file.** AQL and AML contain single quotes and newlines, which break shell quoting. Write the parameters as one JSON object to a file in your scratchpad (or another temp location your runtime lets you use without approval) with your file-writing tool, then pipe it in. Only JSON escaping applies — newlines as `\n`, double quotes as `\"`; single quotes need none:

```sh
cat <scratchpad>/viz-params.json | holistics mcp execute_viz
```

where the file holds e.g. `{"dataset_uname": "ecommerce", "title": "Orders by status", "viz": "DataTable {\n  dataset: ecommerce\n  fields: [r(orders.status)]\n}"}`. Stdin must be that JSON object — piping a raw `.aml` file fails. Overwrite the same file on later calls rather than deleting it.

Short payloads without single quotes can go inline as one single-quoted argument: `holistics mcp fetch_dataset '{"dataset_uname": "ecommerce"}'`.

Avoid heredocs and files outside your allowed directories for the payload: Claude Code asks for approval on every such call.

The `⚠ Code sync is not running` line some calls print is a reminder that the cloud may not have your latest local edits (see `sync-code` above), not an error from the tool.

Versions

The database has no other skills named setup-amql-development.

Database snapshot: 13.11.2026 · package version 5bedac17ec70 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100develop-amql
    Write and edit AML/AQL code for Holistics models, datasets, dashboards, and metrics. Use this whenever the user wants to create or modify a model, dataset, dashboard page, AQL metric, or any file in an AMQL project.
  • 100holistics-migrate-power-bi
    Migrate a Power BI semantic model (TMDL + DAX) and reports to Holistics AMQL assets (AML models, datasets, dashboards, AQL/SQL metrics). Use this when converting a .pbix/.pbip project, translating DAX measures, mapping TMDL tables and relationships to Holistics models, or…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.