chore: introduce agent development kit skills

rahulrajesh-klarity · rahulrajesh-klarity · commit d990ac2a89a0 · 2026-07-03T20:42:11.000-07:00
diff --git a/gemini-extension.json b/gemini-extension.json
@@ -7,5 +7,5 @@
       "url": "https://api.klarity.ai/mcp"
     }
   },
-  "contextFileName": "skills/klarity-process-context-graph/SKILL.md"
+  "contextFileName": "skills/klarity-agent-builder-using-klarity/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,6 +43,12 @@ 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(
@@ -87,6 +93,22 @@ class KlarityMCPMetadata:
     ),
     license_spdx="Apache-2.0",
     repository_url="https://github.com/Klarity-AI/klarity-mcp",
+    skills=(
+        "klarity-process-context-graph",
+        "klarity-agent-builder-using-klarity",
+        "klarity-agent-builder-start",
+        "klarity-agent-builder-home",
+        "klarity-agent-builder-objective",
+        "klarity-agent-builder-current-state",
+        "klarity-agent-builder-diagnose",
+        "klarity-agent-builder-propose",
+        "klarity-agent-builder-spec",
+        "klarity-agent-builder-skill-track",
+        "klarity-agent-builder-skill-discovery",
+        "klarity-agent-builder-skill-outline",
+        "klarity-agent-builder-skill-build",
+    ),
+    gemini_context_skill="klarity-agent-builder-using-klarity",
 )
 
 
diff --git a/skills/klarity-agent-builder-current-state/SKILL.md b/skills/klarity-agent-builder-current-state/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: klarity-agent-builder-current-state
+description: Build and maintain an accurate, factual map of how work happens in a workspace, plus a customer-ready read-out. Pure factual capture, no opinions or recommendations. Reads the project scope, pulls process data from Klarity in parallel mini-phases, checks the data against reality, and writes a structured baseline plus an HTML report. Use after objective, or when the user says "current state," "map the workspace," "read-out," or "show me how the work runs."
+---
+
+# Current state
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="current_state")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
+
+This step produces a visual HTML artifact; the fetched instructions include a Rendering section — follow it (fetch the template, inject data into the JSON data-islands, write the file, tell the user to open it).
diff --git a/skills/klarity-agent-builder-diagnose/SKILL.md b/skills/klarity-agent-builder-diagnose/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-diagnose
+description: Turn the project objective and the validated current-state baseline into a set of evidence-backed, scored opportunities. Generates hypotheses against the objective, investigates each one with parallel subagents, scores them on transparent evidence-based axes, and writes a findings report. Runs after current-state. Use when the user says "diagnose," "find opportunities," or "what should we automate."
+---
+
+# Diagnose
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="diagnose")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-home/SKILL.md b/skills/klarity-agent-builder-home/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: klarity-agent-builder-home
+description: Renders the Klarity home screen — a single-page HTML artifact showing lifecycle phase progress, current status, and next actions. Invoke when the user says "home," "status," "where am I," or at session start to orient.
+---
+
+# Home
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="home")` and follow it.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
+
+This step produces a visual HTML artifact; the fetched instructions include a Rendering section — follow it (fetch the template, inject data into the JSON data-islands, write the file, tell the user to open it).
diff --git a/skills/klarity-agent-builder-objective/SKILL.md b/skills/klarity-agent-builder-objective/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-objective
+description: Set up a new automation project by capturing the things the data cannot tell us: the outcome the user wants, what kind of value matters, where to focus, which tools are allowed, what is off-limits, and who owns it. Writes project.md and manifest.md. Use when the user says "start a project," "set an objective," "new engagement," or when no project exists for the workspace.
+---
+
+# Objective
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="objective")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-propose/SKILL.md b/skills/klarity-agent-builder-propose/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: klarity-agent-builder-propose
+description: Fitness-check a candidate, extract pain points, match tools, and produce an interactive HTML recommendation artifact. Use when the user says "propose," "spec this out," "what should the agent do," or "recommend for X."
+---
+
+# Propose
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="propose")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
+
+This step produces a visual HTML artifact; the fetched instructions include a Rendering section — follow it (fetch the template, inject data into the JSON data-islands, write the file, tell the user to open it).
diff --git a/skills/klarity-agent-builder-skill-build/SKILL.md b/skills/klarity-agent-builder-skill-build/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-skill-build
+description: Load when the skill track has an approved outline and needs the final installable bundle produced — the conductor invokes this after Gate 2 (utterances that reach it: "build it", "generate the bundle", "ship this skill", "make the install steps"). Emits the hub-and-spoke skill bundle, a web-verified install wizard, and a first-run smoke test drawn from the team's real evidence. Needs web search to verify the current install UI against vendor docs. NOT for discovering candidates (that is skill-discovery), NOT for drafting or approving the outline (that is skill-outline), and NOT for any generic non-skill build (there is intentionally no generic build skill).
+---
+
+# Skill build
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="skill_build")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-skill-discovery/SKILL.md b/skills/klarity-agent-builder-skill-discovery/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-skill-discovery
+description: Load when the skill track needs candidate skill cards discovered from a team's workspace evidence — utterances reach it through the conductor, not directly (the track has already set the scope, the runner, and the approved systems). Reads processes, observations, and activity timelines, then surfaces a small set of plain-language candidate cards for the user to triage. NOT for expanding a chosen card into a plan (that is skill-outline), NOT for building the final bundle (that is skill-build), and NOT for general automation opportunities across the org (that is diagnose).
+---
+
+# Skill discovery
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="skill_discovery")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-skill-outline/SKILL.md b/skills/klarity-agent-builder-skill-outline/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-skill-outline
+description: Load when the skill track has a chosen candidate card and needs the full plan expanded and approved before anything is built — the conductor invokes this after Gate 1 with the chosen card plus its internal context. Produces a user-facing outline (the Gate 2 artifact) plus a machine-readable technical spec. Needs web search to verify current integration install paths. NOT for discovering candidate cards (that is skill-discovery), NOT for the critic pass, NOT for shipping the final bundle (that is skill-build), NOT for general automation opportunities (that is diagnose/propose).
+---
+
+# Skill outline
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="skill_outline")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-skill-track/SKILL.md b/skills/klarity-agent-builder-skill-track/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: klarity-agent-builder-skill-track
+description: Conductor for the skill track — turns how a team already works into a reusable, installable skill. Use when the user says "build skills," "make a skill for my team," "turn this process into a skill," or arrives from the start gate's "Build skills" door. NOT for finding general automation opportunities (that is diagnose), NOT for spec'ing an agent or automation (that is propose), NOT for expanding or building a single bundle directly (the stage skills skill-discovery, skill-outline, and skill-build do that under this conductor).
+---
+
+# Skill track
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="skill_track")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
+
+This skill is the client-side CONDUCTOR: it fetches its step instructions but runs the gates and durable project-directory I/O on the client. The tool returns the instructions; this skill runs the loop.
diff --git a/skills/klarity-agent-builder-spec/SKILL.md b/skills/klarity-agent-builder-spec/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-spec
+description: Turn one approved non-skill recommendation into an implementation spec a customer's IT or engineering team can build from. Use when the user says "spec this," "write the build spec," "turn this into a build plan," or after propose hands off a build_candidate whose primitive is not a skill.
+---
+
+# Spec
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="spec")`.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-start/SKILL.md b/skills/klarity-agent-builder-start/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-start
+description: The front door. Two-door intent gate at session start. Invoke when the user says "start," "klarity start," "what can you do," "where do I begin," or opens a session with no active project and no explicit intent. Routes to the skill track (Build skills) or the explore path (Explore & decide).
+---
+
+# Start
+
+This step of the Klarity agent-building lifecycle is served from the Klarity Architect MCP. Do not improvise the methodology — fetch it.
+
+1. Call `get_agent_builder_instructions(step="start")` and follow it (the two-door gate).
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-using-klarity/SKILL.md b/skills/klarity-agent-builder-using-klarity/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: klarity-agent-builder-using-klarity
+description: Entry point for all Klarity work. Establishes the lifecycle, MCP connection, and skill routing. Invoke before any response when the user mentions processes, automation, agents, or ops intelligence.
+---
+
+# Using Klarity
+
+This is the 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.
+
+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 handoff all come from that call.
+2. Follow the returned instructions exactly. They include a **resource manifest** — a list of references/primitives/templates this step needs.
+3. For each manifest entry, call `get_agent_builder_resource(type=..., key=...)` and use the returned content. Fetch on demand; do not skip.
+4. Write outputs to the project directory as the instructions specify.
diff --git a/skills/klarity-agent-builder-using-klarity/tools.md b/skills/klarity-agent-builder-using-klarity/tools.md
diff --git a/tests/test_packaging.py b/tests/test_packaging.py

Original file line number	Diff line number	Diff line change
`@@ -7,5 +7,5 @@`
`7`	`7`	`"url": "https://api.klarity.ai/mcp"`
`8`	`8`	`}`
`9`	`9`	`},`
`10`		`- "contextFileName": "skills/klarity-process-context-graph/SKILL.md"`
	`10`	`+ "contextFileName": "skills/klarity-agent-builder-using-klarity/SKILL.md"`
`11`	`11`	`}`