Skip to content

Establish agent skills as source of truth, simplify example content#95

Draft
pkosiec wants to merge 1 commit into
mainfrom
pkosiec/agent-skills-unification
Draft

Establish agent skills as source of truth, simplify example content#95
pkosiec wants to merge 1 commit into
mainfrom
pkosiec/agent-skills-unification

Conversation

@pkosiec
Copy link
Copy Markdown
Member

@pkosiec pkosiec commented May 14, 2026

Summary

Companion to databricks-agent-skills PR #76.
⚠️ databricks/databricks-agent-skills#76 should be merged first!

Establishes Databricks agent skills as the single source of truth for implementation patterns, while keeping DevHub templates as the discovery and context layer.

What changes for agents

  • Preamble: New "Implementation guidance" section in dev-guidelines.md tells agents the template describes what to build, and installed skills provide the how.
  • Intent blocks: Each intent file (recipe, cookbook, example) now instructs agents to treat skills as the source of truth when template content and skills overlap.
  • Example prompts: Simplified buildFullPrompt() — removed duplicate CLI auth verification steps that the local-bootstrap block already covers.

What changes for users

  • Example pages: inventory-intelligence content simplified to outcome-only (Data Flow + What to Adapt). The "Setup — interview the user" section is removed (see below).
  • Cookbook intro: ai-chat-app intro now mentions that installed skills provide implementation patterns.
  • Recipe pages: No content changes. Recipes still serve humans browsing the site with full implementation details.

Why we removed the "interview the user" pattern

The inventory-intelligence example had a structured 8-question interview (workspace URL, CLI profile, catalog, warehouse ID, Lakebase project, data mode, Genie tab, forecast model) baked into content.md. This is no longer needed because:

  1. The intent blocks (intent-example.md) already define the conversational flow — clarify intent, pin down decisions, ask one question at a time
  2. The skills individually prompt for the pieces they need (profile name, Lakebase project, etc.) as part of their own workflows
  3. The example's template/README.md has the actual setup instructions

With skills as the source of truth, agents discover what to ask as they go — they don't need a pre-baked questionnaire.

Test plan

  • npm run build passes
  • npm run test passes (255/255)
  • npm run typecheck passes
  • Example pages render correctly (spot-check /templates/inventory-intelligence)
  • Agent prompt includes "Implementation guidance" preamble (spot-check /api/markdown)
  • Cookbook intro reads naturally (/templates/ai-chat-app)

@pkosiec pkosiec force-pushed the pkosiec/agent-skills-unification branch from 3c62aca to 906cc32 Compare May 15, 2026 14:07
@pkosiec pkosiec changed the title Delete absorbed recipes, convert cookbooks to skill references Establish agent skills as source of truth, simplify example content May 15, 2026
@pkosiec pkosiec force-pushed the pkosiec/agent-skills-unification branch from 906cc32 to 703a5de Compare May 15, 2026 15:55
Add "Implementation guidance" preamble to dev-guidelines.md telling
agents to use installed Databricks skills for implementation patterns.
Update intent blocks (recipe, cookbook, example) to treat skills as
the authoritative source when template content overlaps.

Simplify inventory-intelligence example to outcome-only (remove
structured interview and design sections). Remove duplicate CLI auth
verification from buildFullPrompt() — the local-bootstrap block
already handles it.

Add skills reference to ai-chat-app cookbook intro.

Co-authored-by: Isaac
@pkosiec pkosiec force-pushed the pkosiec/agent-skills-unification branch from 703a5de to 19c1d7c Compare May 15, 2026 16:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant