Move agent-runtime tips out of SKILL.md into references/

[vmariiechko]

Related Issue

(no related issue)

Summary

Refactors the dbx-ro-query asset's operational notes so SKILL.md stays agent-agnostic and per-runtime quirks live in <target_dir>/skills/dbx-ro-query/references/agent-<name>.md. Matches the agentskills.io references/ convention: the parent SKILL.md carries one on-demand pointer; each runtime's quirks live in a sibling file the agent loads only when it hits the relevant issue. Prevents SKILL.md from drifting toward a multi-vendor compatibility matrix as more agents are documented.

The agent-codex.md and agent-cursor.md files are not speculative: their content was validated by independent Codex and Cursor test sessions running v1.6.0 against a live Databricks workspace, and the findings are folded back in.

Changes

• New file references/agent-claude-code.md: 2-minute Bash tool default timeout (warehouse cold-start hint); exit-code echo pattern reframed for parseable rejection evidence (Claude Code's harness already surfaces non-zero exits to the model).
• New file references/agent-codex.md: sandbox network_access = true setting; login: false on shell_command for clean captured output (was inline in SKILL.md previously); PowerShell Measure-Command warning; warehouse env var note. Validated by a live Codex test session.
• New file references/agent-cursor.md: ready-to-paste .cursor/rules/dbx-ro-query.mdc rule snippet (Cursor does NOT auto-discover .cursor/skills/); terminal runtime notes confirming exit codes are surfaced natively; warehouse warm-up note. Validated by a live Cursor 3.3.x / Composer 2 test session.
• SKILL.md operational notes: removed the inline Codex bullet; added a single generic line pointing at references/agent-<runtime>.md. Other notes remain agent-agnostic.
• Schema success_message: each per-agent section now points at its references/ file rather than restating wiring inline. Cursor section explicitly flags that .cursor/skills/ is NOT auto-discovered, so users see this at install time.
• Asset-level README.md: new Troubleshooting section documenting (a) the generic DATABRICKS_CONFIG_PROFILE resolution failure both Codex and Cursor reports surfaced, and (b) the Codex-specific sandbox network block.
• Per-asset tests: EXPECTED_FILES grows by three (agent-claude-code.md, agent-codex.md, agent-cursor.md); two new test functions assert SKILL.md points at references/ and every references file starts with an H1 heading.

Change Area

• Core template (template/, schema, helpers)
• Asset Library (assets/<name>/)
• Both
• Docs / tests / infrastructure only

Configuration Axes Affected

• Environment setup (full/minimal, dev environment)
• Compute type (classic/serverless/both)
• Permissions / RBAC
• CI/CD pipelines (Azure DevOps, GitHub Actions, GitLab)
• Cloud provider (Azure/AWS/GCP)
• Unity Catalog / schemas
• Template schema (databricks_template_schema.json)
• Template helpers (library/helpers.tmpl)
• Asset Library (new asset, asset schema, or framework changes)
• None of the above (docs, tests, infrastructure only)

Testing

• All tests pass (pytest tests/ -V): 2317 passed, 163 skipped. Asset-only suite: 79 passed in 33s.
• Manual asset install tested: databricks bundle init against a fresh project lays down all 5 expected files (SKILL.md + script + 3 references) at the correct paths under <target_dir>/skills/dbx-ro-query/. The new success_message renders the per-agent pointers exactly as designed.
• New tests added: test_skill_references_pointer_present, test_references_files_have_headings.

External validation:

• Codex test session (independent agent, GPT model, fresh install of v1.6.0): all five live query scenarios passed (SELECT 1 scalar, SHOW CATALOGS lines, DESCRIBE samples.nyctaxi.trips tsv, DROP TABLE foo rejected exit 1, SELECT 1; DROP TABLE foo rejected exit 1). Confirmed login: false advice is still accurate; identified sandbox network gap; identified Measure-Command PowerShell pitfall. Findings folded into references/agent-codex.md.
• Cursor test session (independent agent, Composer 2, fresh install of v1.6.0): same five live query scenarios passed. Identified that .cursor/skills/ is not auto-discovered and the wiring path is .cursor/rules/*.mdc. Drafted the rule snippet, which is now bundled in references/agent-cursor.md. Confirmed exit codes and stdout/stderr are surfaced natively to the model.

Asset Changes

• Asset installs standalone via databricks bundle init . --template-dir assets/dbx-ro-query --output-dir <dir>.
• Asset is self-contained (no references to library/helpers.tmpl or other assets).
• tests/configs/assets/dbx_ro_query.json already in place from v1.6.0.
• Asset already appears in ASSETS.md catalog (no row change needed).

Checklist

• Go template syntax is valid (no unclosed {{ }} blocks).
• No .tmpl files appear in generated output.
• Generated YAML files are valid (asset ships no YAML).
• Documentation updated: SKILL.md, schema success_message, asset-level README troubleshooting section, three new references files, CHANGELOG [Unreleased] entries (Added + Changed sections).