docs: document Agent Skills for the Cube AI agent

[keydunov]

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

Description of Changes Made

Documents Agent Skills — reusable, named instruction packages the Cube AI agent runs on demand, authored as Markdown in the data model alongside rules and certified queries.

Two pages, split by audience

• docs-mintlify/admin/ai/skills.mdx — Skills (authoring/config, developer-facing), parallel to Rules and Certified queries: agents/skills/ file layout, frontmatter contract (title/description required, name/instructions overrides), YAML inlining, multi-agent space targeting, deploy/test-on-a-branch flow, and permissions.
• docs-mintlify/docs/explore-analyze/skills.mdx — Agent skills (explorer/viewer-facing), next to Analytics Chat: running a skill via skill buttons, the / menu, and automatic matching, plus the add-context-before-run UX.

Both are wired into docs.json, the AI overview gets a Skills card + bullet, and the two pages cross-link.

Docs-site guidance

Establishes that /docs-mintlify is the active docs site and /docs is legacy/deprecated:

• Updated root CLAUDE.md
• Added docs-mintlify/CLAUDE.md with Mintlify conventions
• Marked docs/CLAUDE.md as deprecated

Notes for reviewers

• Built locally with the Mintlify dev server; both pages render and mintlify broken-links reports no broken links from the new pages.
• Screenshots are left as {/* TODO */} placeholders (skill buttons, / menu, the styled /skill-name token).
• ⚠️ The agents/skills/ directory and the skills/instructions YAML keys are documented by analogy to rules/certified-queries — please confirm the exact frontmatter keys and override rules against the live runtime markdown parser before publishing.

🤖 Generated with Claude Code

[claude]

Claude finished @keydunov's task in 1m 13s —— View job

---

Code review — docs: document Agent Skills

Review summary — 0 high, 4 medium, 2 low (docs-only PR)

Checklist

• Read PR diff and both new pages
• Cross-check with admin/ai/index.mdx, docs.json, and CLAUDE.md changes
• Note inconsistencies and ambiguities

The split into authoring (admin/ai/skills.mdx) vs. usage (docs/explore-analyze/skills.mdx), the parallel structure with rules/certified-queries, the docs.json wiring, the AI overview Card + bullet, and the cross-links all look right. The CLAUDE.md changes establishing /docs-mintlify as the active site and marking /docs deprecated are clean. Below are the things worth tightening before publishing — most echo the author's own ⚠️ in the PR body.

Medium

1. Frontmatter required-ness contradicts itself between Markdown and YAML.
docs-mintlify/admin/ai/skills.mdx:51-57 says name and instructions are optional (with fallbacks to filename and body). Then :75-76 says: "Inline skills accept the same properties as Markdown ones — name, title (required), description (required), and instructions (required)." For inline YAML they're effectively required (no filename, no body to fall back to), but as written the two statements read as a direct contradiction. Either split the table into Markdown-file vs. inline-YAML required columns, or restate the rule explicitly: "in inline YAML, name and instructions become required because there is no file name or body to fall back to."

2. "Nested folders don't namespace" vs. multi-agent placement under agents/skills/<space-name>/.
:45-47 says nested folders are allowed for organization but do not namespace skills (names must be unique across the whole tree). :82-83 then says, for multi-agent, to attach skills to a space by placing them under agents/skills/<space-name>/. That is namespacing by folder. Reconcile: either <space-name>/ is a recognized top-level convention (call that out as the one exception), or attachment is by inline-YAML only and the folder example should be removed.

3. Directory tree in admin/ai/index.mdx doesn't show skills/.
docs-mintlify/admin/ai/index.mdx:18-30 lists rules/ and certified_queries/ in the project layout but not agents/skills/. New users following the layout example won't see where skills live. Add a skills/ entry alongside rules/ and certified_queries/.

4. Directory naming: skills/ vs. certified_queries/ (snake_case).
The existing convention shown in index.mdx is snake_case (certified_queries/). skills/ is single-word so this isn't broken, but worth confirming with whoever owns the runtime parser that the path is literally agents/skills/ and not agents/skill_packs/ or similar — same ⚠️ the author already flagged.

Low

5. description guidance is split across two sections.
:54 says description is what's matched for auto-selection. :124-125 (Writing effective skills) repeats this as a bullet. Fine, but the bullet could link directly to the table to avoid future drift.

6. Slash-menu trigger wording (docs/explore-analyze/skills.mdx:28-30).
"Type / in the chat input to open the skill menu." If the input already has any text before the /, does it still trigger? Worth one sentence on the trigger conditions, since users will hit this corner immediately.

Things that look good

• Progressive disclosure section (admin/ai/skills.mdx:86-98) — clear and correctly explains why descriptions matter for auto-matching.
• Permissions section cleanly delineates author vs. run access and links to roles.
• "Adding context before you run" with the /weekly-revenue-report for EMEA, last 6 weeks example makes the styled-token UX concrete despite the screenshot still being a TODO.
• docs.json insertions are at the right spots (right after analytics-chat, and in the AI admin group right after certified-queries).
• Cross-links in both directions between the two new pages, and from the AI index Card.

· `docs/agent-skills`

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Jun 3, 2026, 2:55 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @keydunov's task in 1m 34s —— View job

---

Code review — refinements pass

Verdict: 0 high, 2 medium, 2 low. The author addressed the frontmatter contradiction (M1) and reworded the "anywhere you work with the agent" framing cleanly. A couple of items from the previous pass are still open.

Details

Checklist

• Re-read both pages after the refinement commit (c534663)
• Cross-check against prior review threads
• Note what was resolved vs. what still applies

Resolved since last pass

• M1 — Frontmatter required-ness. The table now omits instructions (the Markdown body is the source), and the YAML inline section explicitly explains why instructions is needed there. Clear.
• Framing now consistently says "wherever you work with the agent" rather than Analytics-Chat-only. Good.

Still open

M2 — Nested folders namespacing is still self-contradictory.
docs-mintlify/admin/ai/skills.mdx:46-48 says nested folders are organizational only and do not namespace skills (names must be unique tree-wide). Then :85-86 says, for multi-agent, attach a skill to a space by placing the file under agents/skills/<space-name>/. That is namespacing by folder. Either <space-name>/ is a recognized top-level convention (call it out as the one exception) or attachment is by inline YAML only and the folder example should be removed.

M3 — admin/ai/index.mdx directory tree still omits skills/.
docs-mintlify/admin/ai/index.mdx:18-30 lists rules/ and certified_queries/ but not agents/skills/. New users following the layout example won't see where skills live. One line under certified_queries/ is enough.

L4 — Directory naming (skills/ vs. snake_case neighbors). Author's own ⚠️ in the PR body still applies — confirm with the runtime parser that the literal path is agents/skills/. Single-word so no in-doc inconsistency, but worth verifying before publishing.

L6 — Slash-menu trigger wording (docs/explore-analyze/skills.mdx:29).
"Type / in the chat input to open the skill menu." Still doesn't say whether / triggers only at the start of input or anywhere. Users will hit this corner immediately — one sentence on the trigger conditions would close it.

Things that look good

• Progressive disclosure section (admin/ai/skills.mdx:91-103) still clear.
• The "anywhere you work with the agent" reframing is consistent across both pages.
• Cross-links updated correctly (Analytics-Chat-specific link text replaced with generic).
• Inline-YAML clarification now reads naturally.

· `docs/agent-skills`

[claude]

Claude finished @keydunov's task in 1m 2s —— View job

---

Code review — third pass

Verdict: 0 high, 2 medium, 2 low (docs-only). Same items as my prior pass remain open after the most recent commit; the resolved items stay resolved.

Details

Checklist

• Re-read admin/ai/skills.mdx, docs/explore-analyze/skills.mdx, admin/ai/index.mdx at HEAD
• Compare against prior review threads
• Confirm what was addressed since c534663

Resolved (and still resolved)

• M1 — Frontmatter contradiction. Markdown table no longer lists instructions; YAML section explicitly explains why instructions is required inline. Clear.
• Framing consistently says "wherever you work with the agent" — Analytics Chat, Workbooks, dashboards, IDE — across both pages and cross-links.

Still open

M2 — Nested folders vs. multi-agent space placement (still contradictory).
docs-mintlify/admin/ai/skills.mdx:46-48 — "Nested folders are allowed for organization but do not namespace the skill — skill names must be unique across the entire skills/ directory."
docs-mintlify/admin/ai/skills.mdx:84-86 — "attach skills to a specific space by inlining them under that space's skills key (or by placing Markdown files under agents/skills/<space-name>/)."

The second sentence is namespacing by folder for space attachment. Either call <space-name>/ out as the one recognized convention (an exception to "folders don't namespace"), or drop the folder example and say space attachment is inline-YAML only. Fix this →

M3 — admin/ai/index.mdx directory tree still omits skills/.
docs-mintlify/admin/ai/index.mdx:18-30 lists rules/ and certified_queries/ but not agents/skills/. New users following the layout example won't see where skills live. Adding one line under certified_queries/ is enough. Fix this →

L4 — Directory naming. Author's own ⚠️ in the PR body still applies — confirm with the runtime parser that the literal path is agents/skills/ (and that the skills/instructions YAML keys match) before publishing. No in-doc inconsistency, just a verification step.

L6 — Slash-menu trigger wording. docs/explore-analyze/skills.mdx:34 — "Type / in the chat input to open the skill menu." Still doesn't say whether / triggers only at the start of input or anywhere (e.g. after existing text). Users will hit this corner immediately. One sentence on the trigger conditions would close it. Fix this →

Things that look good

• Progressive disclosure section (admin/ai/skills.mdx:91-103) — clearly explains why descriptions matter for auto-matching, and notes the full body never leaves the server.
• Permissions section cleanly delineates author vs. run access on both pages.
• The "Adding context before you run" UX with /weekly-revenue-report for EMEA, last 6 weeks makes the styled-token interaction concrete despite the screenshot placeholder.
• docs.json insertions land at the right spots; AI overview Card + bullet are wired correctly.
• docs-mintlify/CLAUDE.md establishes the active-site convention; root and legacy CLAUDE.md updated consistently.

· `docs/agent-skills`