00b-agent-spec-and-tool-plan - SKILL.md Agent Skill

name: 00b-agent-spec-and-tool-plan description: > Use when deriving a Databricks Agent Spec and Agent Tool Plan from docs/design_prd.md before building Track A agents. Covers web-researched MCP recommendations, Databricks managed MCP choices, dynamic SQL MCP catalog/schema inputs, optional Knowledge Assistant selection, and validation of docs/agent_spec.yaml plus docs/agent_tool_plan.yaml. license: Apache-2.0 metadata: last_verified: "2026-06-05" upstream_sources: [] volatility: high author: "prashanth-subrahmanyam" version: "1.0.0" domain: "genai-agents" pipeline_position: "F0b" consumes: "docs/design_prd.md" produces: "docs/agent_spec.yaml, docs/agent_tool_plan.yaml" fields_read: - agent.system_prompt - agent.capabilities - agent.model - agent.must_do - agent.must_not_do - agent.benchmark_seeds.coverage_buckets - agent.benchmark_seeds.seed_examples - agent.tools - agent.mcp_servers - agent.knowledge_base_backend - agent.external_integrations - governance.scorer_suite.guidelines - governance.scorer_suite.custom_scorer_rules - governance.scorer_suite.judge_questions - governance.verification.smoke_test_cases - governance.llm_role_endpoints.llm_judge_default.endpoint - selected_tools - selected_mcp_servers - runtime_guardrails.tool_shaped_scorers - verification.tool_smoke_tests

Agent Spec And Tool Plan

Purpose

This skill bridges the AppKit/Lakebase application design phase and the Track A agent build phase. It turns docs/design_prd.md into a concrete docs/agent_spec.yaml, then turns the spec plus user tool choices into docs/agent_tool_plan.yaml.

The skill does not create Databricks resources, install MCP connections, wire agent code, or deploy apps. It produces planning artifacts that later prompts consume.

When To Use

Use this skill for:

Creating an Agent Spec after docs/design_prd.md exists.
Asking the IDE to web search for MCPs relevant to the use case.
Selecting Databricks managed MCPs: Genie, Vector Search, SQL, UC Functions.
Selecting external MCP candidates through managed OAuth, Marketplace, custom HTTP connections, or Dynamic Client Registration.
Adding a no-prerequisite SQL MCP path over existing Unity Catalog tables by providing agent_sql_catalog, agent_sql_schema, and warehouse ID.
Deciding whether a Knowledge Assistant should be created.

Inputs

Input	Required	Description
`prd_path`	yes	Usually `docs/design_prd.md`.
`agent_spec_path`	yes	Usually `docs/agent_spec.yaml`.
`agent_tool_plan_path`	yes	Usually `docs/agent_tool_plan.yaml`.
`agent_spec_ref`	no	Path to existing Agent Spec for downstream skills that consume it (alias of `agent_spec_path`).
`agent_tool_plan_ref`	no	Path to existing Tool Plan for downstream skills that consume it (alias of `agent_tool_plan_path`).
`agent_model`	no	Databricks serving endpoint used by the agent LLM. Defaults to `databricks-claude-sonnet-4-6`.
`agent_sql_catalog`	no	Catalog the SQL MCP may query.
`agent_sql_schema`	no	Schema the SQL MCP may query.
`agent_sql_warehouse_id`	no	Warehouse for SQL MCP `_meta.warehouse_id`.
`agent_sql_table_allowlist`	no	Tables allowed for SQL MCP; empty means schema-scope with read-only guardrails.
`mcp_research_mode`	no	`none`, `managed_only`, or `web_research`.

Agent Spec Contract

docs/agent_spec.yaml must follow references/agent-spec-schema.md.

Required top-level keys:

schema_version
source_prd
agent (includes must_do[], must_not_do[], benchmark_seeds.coverage_buckets[], benchmark_seeds.seed_examples[])
tool_recommendations
mcp_research
knowledge_assistant
governance (includes scorer_suite.{guidelines, custom_scorer_rules, judge_questions}, verification.smoke_test_cases[], llm_role_endpoints.llm_judge_default.endpoint)

The spec may recommend tools, but it must not mark every recommendation as selected. Final selection belongs in docs/agent_tool_plan.yaml.

Tool Plan Contract

docs/agent_tool_plan.yaml must follow references/tool-plan-schema.md.

Required top-level keys:

schema_version
source_agent_spec
runtime_config (includes llm.{provider, endpoint, api_base_url, api_mode, model_config})
selected_tools
selected_mcp_servers
knowledge_assistant
resource_grants
runtime_guardrails (includes tool_shaped_scorers[] derived mechanically from selected_tools[])
verification (includes tool_smoke_tests[] — one entry per selected_tools[] entry)

Eval Authoring Rule

Eval/governance content is layered across three places, and each place has a strict tool-awareness contract.

Layer	Where	Tool-aware?	What lives here
Spec (generic)	`docs/agent_spec.yaml`	No — tools are not yet selected	`agent.must_do[]`, `agent.must_not_do[]`, `agent.benchmark_seeds.{coverage_buckets, seed_examples}`, `governance.scorer_suite.{guidelines, custom_scorer_rules, judge_questions}`, `governance.verification.smoke_test_cases[]`, `governance.llm_role_endpoints.llm_judge_default.endpoint`
Plan (tool-shaped)	`docs/agent_tool_plan.yaml`	Yes — derived mechanically from `selected_tools[]`	`verification.tool_smoke_tests[]` (one per selected tool, use-case-shaped prompt + observable signal); `runtime_guardrails.tool_shaped_scorers[]` (e.g. `ka_citation_present`, `RetrievalGroundedness`, `genie_sql_correctness`, `sql_readonly_compliance`)
Consumer (union)	sections 46/50/51/52	Reads BOTH	Smoke set = Spec ∪ Plan; benchmark rows = Spec base ∪ Plan tool-shaped append; scorer suite = Spec generic ∪ Plan tool-shaped (deduped); failure-shape `tool_call_empty` only fires for tools in `selected_tools[]`

Authoring rules:

Section 38 (Spec) never authors tool-shaped fields. No ka_citation_present, no RetrievalGroundedness, no genie_*, no sql_* scorer hints. No assertions like "use Genie to look up X" in seed_examples. Tools are not selected at this step.
Section 39 (Plan) mechanically derives the tool-shaped fields from selected_tools[] using the table in references/tool-plan-schema.md § Tool-shaped Derivation Rules. Tool families absent from selected_tools[] contribute zero entries.
Sections 46/50/51/52 (Consumers) read both files and union them. KA absent in the Plan ⇒ no KA scorer registered, no KA smoke test, no KA dataset row, no KA failure-shape branch.

Validation at exit (section 39):

verification.tool_smoke_tests[] length equals selected_tools[] length.
Every runtime_guardrails.tool_shaped_scorers[] entry maps to a tool family present in selected_tools[].
No tool_shaped_scorers[] entry exists for a tool family that is selected: false or absent.

Runtime Model Route Rule

docs/agent_spec.yaml must include the backing Databricks model serving endpoint at:

agent:
  model: "databricks-claude-sonnet-4-6"

docs/agent_tool_plan.yaml must convert that backing model into the runtime route:

runtime_config:
  llm:
    provider: "databricks"
    endpoint: "docs/agent_spec.yaml.agent.model"
    api_base_url: null
    api_mode: "databricks_openai_compatible"
    model_config:
      endpoint_key: "llm_endpoint"
      api_base_url_key: "llm_api_base_url"
      api_mode_key: "llm_api_mode"

Rules:

Treat agent.model as a raw/backing Databricks serving endpoint name.
If the user supplies agent_model, copy it exactly into agent.model.
If the user does not supply agent_model, set agent.model to databricks-claude-sonnet-4-6.
Do not store vague labels such as Claude, GPT, best model, or small model.
Do not require AI Gateway in the core flow. Gateway can be introduced later by changing only runtime_config.llm.
The Track A agent must consume runtime_config.llm through ModelConfig as llm_endpoint, llm_api_base_url, and llm_api_mode, not by hardcoding any endpoint in Python.

Dynamic SQL MCP Rule

When SQL MCP is selected, the plan must include:

selected_mcp_servers:
  - name: sql_uc_schema_query
    server_type: sql
    url_template: "{workspace_host}/api/2.0/mcp/sql"
    auth: OBO
    meta:
      warehouse_id: "{agent_sql_warehouse_id}"
    scope:
      catalog: "{agent_sql_catalog}"
      schema: "{agent_sql_schema}"
      allowed_tables: []
    readonly: true

The matching tool must include guardrails:

selected_tools:
  - kind: mcp
    name: sql_uc_schema_query
    mcp_server_ref: sql_uc_schema_query
    readonly: true
    guardrails:
      allowed_statements: ["SELECT", "DESCRIBE", "EXPLAIN"]
      forbidden_statements: ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "CREATE", "MERGE", "TRUNCATE"]
      require_fully_qualified_names: true
      default_catalog: "{agent_sql_catalog}"
      default_schema: "{agent_sql_schema}"

Web Research Rule

If mcp_research_mode: web_research, use the official MCP Registry as the authoritative discovery source before broader web search:

Search the public registry UI at https://registry.modelcontextprotocol.io.
Use the registry REST API documented at https://modelcontextprotocol.io/registry/registry-aggregators#consuming-the-mcp-registry-rest-api.
Prefer GET https://registry.modelcontextprotocol.io/v0.1/servers?limit=100 for discovery, following metadata.nextCursor for additional pages.
Use GET /v0.1/servers/{serverName}/versions and GET /v0.1/servers/{serverName}/versions/latest for candidate version details. URL-encode serverName.
Ignore candidates with registry status: deleted; mark deprecated candidates as confidence: low unless there is no viable alternative.
Use general web search only to enrich registry candidates with vendor docs, Databricks compatibility notes, security posture, or examples.

Record findings under mcp_research.candidates[] with registry metadata, source URLs, version/status, integration notes, and confidence. Do not install or configure any MCP connection during Agent Spec creation.

Validation

Before exiting either prompt:

Parse the YAML.
Confirm all required top-level keys exist.
Confirm agent.model is present and is not n/a.
Confirm agent.model does not contain spaces and does not look like a prose label.
Confirm every selected_tools[].mcp_server_ref resolves to a selected_mcp_servers[].name.
Confirm SQL MCP is read-only unless the user explicitly selected write access.
Confirm KA is either selected with a source strategy or skipped with knowledge_assistant.selected: false.