chore: introduce agent development kit skills (#7)

rahulrajesh-klarity · web-flow · commit c5569760f612 · 2026-07-07T14:00:19.000-07:00
* chore: introduce agent development kit skills

* chore: include documentation for agent builder

* chore: bump up version
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",
-    "version": "1.0.0"
+    "version": "1.1.0"
   },
   "plugins": [
     {
@@ -17,7 +17,7 @@
         "url": "https://github.com/Klarity-AI/klarity-mcp.git"
       },
       "description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "homepage": "https://www.klarity.ai/",
       "license": "Apache-2.0",
       "keywords": [
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "klarity",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",
   "author": {
     "name": "Klarity Intelligence, Inc.",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "klarity",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",
   "author": {
     "name": "Klarity Intelligence, Inc.",
diff --git a/docs/docs.json b/docs/docs.json
@@ -59,7 +59,7 @@
               "guides/transformation-thesis",
               "guides/chain-with-connectors",
               "guides/deep-research",
-              "guides/code-and-agents"
+              "guides/agent-builder"
             ]
           },
           {
@@ -88,7 +88,8 @@
               "tools/process-index",
               "tools/observations-and-changes",
               "tools/artifacts",
-              "tools/workspace"
+              "tools/workspace",
+              "tools/agent-builder"
             ]
           }
         ]
diff --git a/docs/guides.mdx b/docs/guides.mdx
@@ -25,7 +25,7 @@ Each guide is a recipe: an example prompt, the tool chain the assistant should r
   <Card title="Combine with deep research" icon="magnifying-glass-plus" href="/guides/deep-research">
     Your reality vs. external benchmarks — gap analysis with citations on both sides.
   </Card>
-  <Card title="Build agents, skills, and code" icon="robot" href="/guides/code-and-agents">
-    Ground Skills, Custom GPTs, and code generation in your real processes.
+  <Card title="Build an agent with Agent Builder" icon="wand-magic-sparkles" href="/guides/agent-builder">
+    A guided, evidence-grounded workflow from "what should we automate?" to a shipped skill or spec.
   </Card>
 </Columns>
diff --git a/docs/guides/agent-builder.mdx b/docs/guides/agent-builder.mdx
@@ -0,0 +1,64 @@
+---
+title: "Build an agent with Agent Builder"
+description: "A guided, evidence-grounded workflow that takes you from 'what should we automate?' to a shipped skill or a developer-ready spec."
+icon: "wand-magic-sparkles"
+---
+
+Agent Builder is a guided workflow for turning how your organization actually works into automations. Instead of guessing at what to build, the assistant walks you through a lifecycle — scope an objective, map your current state, diagnose the highest-leverage opportunities, propose a prioritized plan, and then either ship a skill or hand a developer a ready-to-build spec. Every recommendation is grounded in real process evidence from your workspace.
+
+You don't need to memorize the steps. Agent Builder is self-guiding: you ask for the instructions once, and it orients you, figures out where you are, and tells you what to run next.
+
+<Note>
+  Agent Builder is gated per workspace. If the tools below aren't available, ask your Klarity admin to enable agent development for your workspace.
+</Note>
+
+## Start here
+
+Ask your assistant to **get the Agent Builder instructions**, or just tell it what you're trying to do ("help me figure out what to automate in procurement"). Under the hood this calls `get_agent_builder_instructions` with the `begin` step — the orientation step that resolves your workspace, reads your intent, and routes you into the right part of the lifecycle.
+
+From there the assistant self-navigates. It fetches the instructions for each step as it reaches it and pulls in supporting resources on demand with `get_agent_builder_resource`. You stay in the loop at every decision point.
+
+## The lifecycle
+
+Agent Builder follows one lifecycle with two entry paths.
+
+| Step | What happens |
+|---|---|
+| **Objective** | Capture the scope of the project — what you're trying to improve and why. |
+| **Current state** | Map the relevant part of your workspace from real process evidence and confirm the readout with you. |
+| **Diagnose** | Score and rank the automation opportunities, each tied to the kind of artifact it would become. |
+| **Propose** | Present a prioritized plan you review and pick from, then route each choice to the right next step. |
+| **Spec** | For a buildable recommendation, produce a developer-ready specification to hand off. |
+
+There's also a **skill track** — when a recommendation is best expressed as a skill, Agent Builder walks you through discovering, outlining, and building it end-to-end. And a read-only **home** view answers "where am I?" and "what's next?" at any point.
+
+## Two ways in
+
+<Steps>
+  <Step title="Build skills">
+    You already know you want to build something. Agent Builder takes you into the skill track — discover candidate skills, outline the one you pick, and build the bundle.
+  </Step>
+  <Step title="Explore and decide">
+    You're not sure what to build yet. Agent Builder walks the full explore chain — objective → current state → diagnose → propose — and only then routes you to a spec or a skill build, grounded in what it found.
+  </Step>
+</Steps>
+
+## What to expect
+
+<Steps>
+  <Step title="It asks before it assumes">
+    When there's a finite set of choices, the assistant presents them and lets you pick rather than guessing. Human checkpoints are built into the workflow by design.
+  </Step>
+  <Step title="No recommendation without evidence">
+    Every diagnosis and proposal is backed by real process data from your workspace. If the evidence isn't there, Agent Builder won't invent it.
+  </Step>
+  <Step title="Your work stays with you">
+    Project artifacts and intermediate state live in a local `./klarity/` project directory on your machine — not in the Klarity backend. You can revisit or resume a project across sessions, and the assistant reconciles where you are against your saved progress.
+  </Step>
+</Steps>
+
+## Watch for
+
+- **Come back after the plan.** The proposal step is interactive — you review and make your picks, then the assistant continues from your selections. Give it your choices before expecting it to build.
+- **One workspace at a time.** Agent Builder resolves the workspace up front. If you work across multiple workspaces, confirm you're in the right one before you start.
+- **Resuming a project.** If you've done work before, start the same way — ask for the instructions. The `begin` step reads your local project state and picks up where you left off instead of starting over.
diff --git a/docs/guides/code-and-agents.mdx b/docs/guides/code-and-agents.mdx
diff --git a/docs/tools/agent-builder.mdx b/docs/tools/agent-builder.mdx
@@ -0,0 +1,64 @@
+---
+title: "Agent Builder"
+description: "Fetch the guided Agent Builder workflow and its supporting resources, step by step."
+icon: "wand-magic-sparkles"
+---
+
+Agent Builder is a guided workflow for turning how an organization works into automations — scope an objective, map current state, diagnose opportunities, propose a plan, then ship a skill or a developer-ready spec. The methodology is served over these two tools rather than shipped in the client, so the assistant fetches each step's instructions as it reaches it.
+
+<Note>
+  These tools are gated by the `enable_agent_development_mcp` workspace setting. They only appear for workspaces where agent development is enabled.
+</Note>
+
+| Tool | When to use |
+|---|---|
+| `get_agent_builder_instructions` | The entry point and the per-step fetcher. Start with `step="begin"` to orient, then fetch each step as the workflow routes to it. |
+| `get_agent_builder_resource` | Pull a supporting resource (reference, primitive, or template) named in a step's manifest — fetched on demand, not up front. |
+
+## `get_agent_builder_instructions`
+
+Fetches one step's instruction body plus the manifest of supporting resources it may draw on.
+
+- **`step`** — the step to fetch. One of: `begin`, `home`, `start`, `objective`, `current_state`, `diagnose`, `propose`, `spec`, `skill_track`, `skill_discovery`, `skill_outline`, `skill_build`.
+
+Returns:
+
+- **`instructions`** — the step's body, with a "Relevant resources" appendix listing the resources you can fetch on demand.
+- **`resource_manifest`** — the same resources as structured `(type, subtype)` pairs. These are **relevance hints**, not required reads — fetch one only when the conversation calls for it.
+
+Always begin with `step="begin"`. The orientation step resolves the workspace, reads the user's intent, and routes into the right part of the lifecycle. There is no `next` field — routing lives in each step's prose, so the workflow self-navigates from `begin` onward.
+
+## `get_agent_builder_resource`
+
+Fetches a single supporting resource named in a step's `resource_manifest`.
+
+- **`type`** — `reference`, `primitive`, or `template`.
+- **`subtype`** — the specific variant. Must be valid for the given `type`; an invalid pairing is rejected.
+
+Returns:
+
+- **`content`** — the resource payload (markdown, HTML, or YAML).
+- **`version`** — the resource version number.
+- **`subtype`** — the resolved subtype.
+
+## The loop
+
+<Steps>
+  <Step title="Orient">
+    Call `get_agent_builder_instructions` with `step="begin"`. Resolve the workspace and let the step route you to the entry point.
+  </Step>
+  <Step title="Walk the lifecycle">
+    Fetch each step's instructions as the workflow reaches it — `objective`, `current_state`, `diagnose`, `propose`, and then `spec` or the skill track. Follow the body's prose to decide what runs next.
+  </Step>
+  <Step title="Pull resources on demand">
+    When a step's manifest names a resource the current work needs, call `get_agent_builder_resource` for that `(type, subtype)`. Don't fetch the whole manifest up front.
+  </Step>
+</Steps>
+
+## Watch for
+
+- **Begin first.** For MCP-only clients with no skills to auto-load, the convention is that the first call is `get_agent_builder_instructions(step="begin")`. Everything else routes from there.
+- **The manifest is a hint.** `resource_manifest` tells you what a step *may* draw on, not what to load. Fetch resources lazily.
+- **Feature-gated.** If these tools aren't present, the workspace doesn't have agent development enabled.
+
+See the [Build an agent with Agent Builder](/guides/agent-builder) guide for the end-to-end walkthrough.
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdx
@@ -17,6 +17,7 @@ Every workflow reduces to: **find the right process(es) → fetch detail → gat
 | [Process observations](/tools/observations-and-changes) | Recent changes, observations, activity timelines, sessions | "What changed?", "what happened?", "why does this run this way?" |
 | [Artifacts](/tools/artifacts) | Document search, content retrieval, in-document text search | The user names a document or recording |
 | [Workspace](/tools/workspace) | List accessible workspaces | Orienting before drilling in |
+| [Agent Builder](/tools/agent-builder) | `get_agent_builder_instructions`, `get_agent_builder_resource` | Building an agent or skill through the guided workflow (gated feature) |
 
 ## Before you call
 
diff --git a/gemini-extension.json b/gemini-extension.json
@@ -1,11 +1,11 @@
 {
   "name": "klarity",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",
   "mcpServers": {
     "klarity": {
       "url": "https://api.klarity.ai/mcp"
     }
   },
-  "contextFileName": "skills/klarity-process-context-graph/SKILL.md"
+  "contextFileName": "skills/agent-builder/SKILL.md"
 }
diff --git a/klarity_mcp/builders.py b/klarity_mcp/builders.py
@@ -190,6 +190,15 @@ def build_gemini_extension_manifest(
     """Output: gemini-extension.json (Gemini CLI extension manifest).
 
     Uses the consolidated `url` key (not `httpUrl`) per Gemini CLI PR #13762.
+
+    PARITY LIMITATION: Gemini's extension schema accepts a single
+    `contextFileName`, so it cannot enumerate every bundled skill the way Codex
+    (`skills: "./skills/"`) and Claude (plugin-dir discovery) do. We point it at
+    the agent-builder entry shim (`metadata.gemini_context_skill`), which is the
+    ADK entry point; that skill's prose routes to the rest of the lifecycle via
+    the MCP tools. The process-context-graph skill and the remaining
+    agent-builder step skills are NOT surfaced to Gemini as separate context
+    files — they remain reachable through the MCP tools the entry shim invokes.
     """
     return {
         "name": metadata.plugin_name,
@@ -200,7 +209,7 @@ def build_gemini_extension_manifest(
                 "url": metadata.mcp_url,
             }
         },
-        "contextFileName": "skills/klarity-process-context-graph/SKILL.md",
+        "contextFileName": f"skills/{metadata.gemini_context_skill}/SKILL.md",
     }
 
 
diff --git a/klarity_mcp/metadata.py b/klarity_mcp/metadata.py
@@ -43,13 +43,19 @@ class KlarityMCPMetadata:
     submission_test_prompts: tuple[str, ...]
     license_spdx: str
     repository_url: str
+    # All skill directory names bundled under skills/. Ships across every client.
+    skills: tuple[str, ...]
+    # The single entry-point skill Gemini's `contextFileName` points at. Gemini's
+    # extension schema accepts exactly one context file, so it cannot enumerate
+    # every skill the way Codex/Claude do; this designates the one that loads.
+    gemini_context_skill: str
 
 
 KLARITY_MCP_METADATA = KlarityMCPMetadata(
     product_name="Klarity",
     app_display_name="Klarity",
     plugin_name="klarity",
-    plugin_version="1.0.0",
+    plugin_version="1.1.0",
     author_name="Klarity Intelligence, Inc.",
     author_email="hello@klarity.ai",
     author_url="https://www.klarity.ai/",
@@ -87,6 +93,11 @@ class KlarityMCPMetadata:
     ),
     license_spdx="Apache-2.0",
     repository_url="https://github.com/Klarity-AI/klarity-mcp",
+    skills=(
+        "klarity-process-context-graph",
+        "agent-builder",
+    ),
+    gemini_context_skill="agent-builder",
 )
 
 
diff --git a/skills/agent-builder/SKILL.md b/skills/agent-builder/SKILL.md
@@ -0,0 +1,16 @@
+---
+name: agent-builder
+description: Entry point for all Klarity agent-building work. Guides you from "what should we automate?" through scoping, diagnosis, and a plan to a shipped skill or developer-ready spec. The methodology is served from the Klarity Architect MCP — invoke before any response when the user mentions processes, automation, agents, or ops intelligence.
+---
+
+# Agent Builder
+
+This is the single entry point for all Klarity agent-building work. The methodology is served from the Klarity Architect MCP — do not improvise it. Fetch it before doing anything else, and let it route you through the rest of the lifecycle.
+
+1. FIRST, call `get_agent_builder_instructions(step="begin")` and follow it before any other agent-building work. Workspace resolution, the lifecycle model, the two-door gate, and the next-step routing all come from that call.
+2. Follow the returned `instructions` exactly. They include a **resource manifest** — references, primitives, and templates the step may draw on.
+3. For each manifest entry the current work needs, call `get_agent_builder_resource(type=..., subtype=...)` and use the returned content. Fetch on demand — the manifest is a relevance hint, not a required read.
+4. Move through the lifecycle by following each step's prose. There is no `next` field; `begin` routes you to the entry step and each step's instructions say what runs next. Fetch each step (`objective`, `current_state`, `diagnose`, `propose`, `spec`, or the skill track: `skill_track` → `skill_discovery` → `skill_outline` → `skill_build`) as you reach it.
+5. Write all durable outputs to the local project directory as the instructions specify. The tools are read-only — they only serve methodology; the client owns project state.
+
+See `tools.md` for the full tool catalog and the lifecycle step list.
diff --git a/skills/agent-builder/tools.md b/skills/agent-builder/tools.md
diff --git a/tests/test_packaging.py b/tests/test_packaging.py

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",`
`3`	`3`	`"name": "klarity",`
`4`		`- "version": "1.0.0",`
	`4`	`+ "version": "1.1.0",`
`5`	`5`	`"description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",`
`6`	`6`	`"author": {`
`7`	`7`	`"name": "Klarity Intelligence, Inc.",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "klarity",`
`3`		`- "version": "1.0.0",`
	`3`	`+ "version": "1.1.0",`
`4`	`4`	`"description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Klarity Intelligence, Inc.",`
Original file line number	Diff line number	Diff line change
`@@ -59,7 +59,7 @@`
`59`	`59`	`"guides/transformation-thesis",`
`60`	`60`	`"guides/chain-with-connectors",`
`61`	`61`	`"guides/deep-research",`
`62`		`- "guides/code-and-agents"`
	`62`	`+ "guides/agent-builder"`
`63`	`63`	`]`
`64`	`64`	`},`
`65`	`65`	`{`
`@@ -88,7 +88,8 @@`
`88`	`88`	`"tools/process-index",`
`89`	`89`	`"tools/observations-and-changes",`
`90`	`90`	`"tools/artifacts",`
`91`		`- "tools/workspace"`
	`91`	`+ "tools/workspace",`
	`92`	`+ "tools/agent-builder"`
`92`	`93`	`]`
`93`	`94`	`}`
`94`	`95`	`]`
Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,11 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "klarity",`
`3`		`- "version": "1.0.0",`
	`3`	`+ "version": "1.1.0",`
`4`	`4`	`"description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",`
`5`	`5`	`"mcpServers": {`
`6`	`6`	`"klarity": {`
`7`	`7`	`"url": "https://api.klarity.ai/mcp"`
`8`	`8`	`}`
`9`	`9`	`},`
`10`		`- "contextFileName": "skills/klarity-process-context-graph/SKILL.md"`
	`10`	`+ "contextFileName": "skills/agent-builder/SKILL.md"`
`11`	`11`	`}`