mandarnilange · mandarnilange · May 2, 2026 · May 2, 2026 · May 2, 2026 · May 2, 2026
diff --git a/README.md b/README.md
@@ -231,10 +231,13 @@ npx skills add mandarnilange/agentforge
 | Skill | Audience | What it does |
 |---|---|---|
 | `agentforge-workflow` | End user | Walks through designing an AgentForge workflow and emits a complete `.agentforge/` directory. |
-| `agentforge-template-author` | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. |
+| `agentforge-cli` | Operator | Conversational interface to the AgentForge CLI — run, monitor, approve gates, apply YAML. |
 | `agentforge-debug` | Operator | Triages stuck or failing pipeline runs from symptom to fix path. |
+| `agentforge-template-author` | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. |
+
+Trigger phrases live in each skill's frontmatter — e.g. *"help me design a PR-triage pipeline"* fires `agentforge-workflow`, *"approve the architect gate"* fires `agentforge-cli`, *"why is pipeline X stuck?"* fires `agentforge-debug`.
 
-Trigger phrases live in each skill's frontmatter — e.g. *"help me design an AgentForge pipeline for PR triage"* fires `agentforge-workflow`; *"why is pipeline X stuck?"* fires `agentforge-debug`. Catalog, changelog, and authoring docs: [`skills/`](skills/).
+**New here?** The [Skill Quickstart](docs/skill-quickstart.md) is a 5-minute, fill-in-the-blanks markdown you edit, paste into your AI agent, and run. Catalog, changelog, and authoring docs: [`skills/`](skills/).
 
 ---
 
@@ -280,6 +283,7 @@ agentforge node start --control-plane-url <url>   # Run as a worker (platform)
 Every deep-dive lives in [`docs/`](docs/). Pick a track:
 
 **Get started**
+- **[Skill Quickstart](docs/skill-quickstart.md)** — 5-minute, fill-in-the-blanks path from zero to your first run via the `agentforge-workflow` skill.
 - **[Getting Started](docs/getting-started.md)** — install to first pipeline run, full CLI walkthrough, resume flow.
 - **[Who Uses It](docs/who-uses-it.md)** — what platform engineers, software engineers, and domain owners each get out of AgentForge.
 - **[Templates](docs/templates.md)** — catalog of bundled pipeline templates.

diff --git a/docs/skill-quickstart.md b/docs/skill-quickstart.md
@@ -0,0 +1,139 @@
+# Skill Quickstart
+
+5 minutes, four steps, zero YAML. You talk; the skill writes the
+pipeline.
+
+---
+
+## 1. Install the skill
+
+```bash
+npm install @mandarnilange/agentforge-core
+npx skills add mandarnilange/agentforge
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+That installs four skills into your AI coding agent:
+
+| Skill | What it does |
+|---|---|
+| `agentforge-workflow` | Designs your pipeline and writes `.agentforge/` |
+| `agentforge-cli` | Runs the CLI for you — *"run my pipeline"*, *"approve gate X"*, *"show me logs"* |
+| `agentforge-debug` | Triages a stuck or failing run |
+| `agentforge-template-author` | (For contributors) ships a new template upstream |
+
+---
+
+## 2. Open your AI coding agent
+
+Any of these works the same way — **Claude Code, Cursor, Codex, Aider,
+Continue.dev**. Open the agent in your project folder. The skills
+auto-load; no restart needed.
+
+---
+
+## 3. Tell the skill what you want
+
+Type a one- or two-sentence description of what you're trying to build.
+The `agentforge-workflow` skill catches the trigger and asks any
+follow-ups it needs (inputs, outputs, gates, budgets, parallelism).
+
+Try one of these as a starting prompt:
+
+**Classic SDLC pipeline**
+> Help me design an AgentForge pipeline that turns a product brief into
+> requirements, an architecture plan, and working code. I want a human
+> approval gate after the architecture phase.
+
+**Content generation with self-review**
+> Build me an AgentForge workflow for producing research-backed blog
+> posts: research the topic, write an outline, draft the post, and
+> self-review for quality before handing me the final version.
+
+**Code review pipeline**
+> I want an AgentForge pipeline that reviews a PR diff and produces
+> severity-tagged review comments plus a security risk score. The
+> reviewers should run in parallel.
+
+**Something brand new**
+> Design an AgentForge workflow for triaging incoming customer-support
+> tickets — classify by category, draft a response, route urgent ones
+> to a human gate.
+
+What the skill does next:
+
+- Recommends a shipped template if one fits (`simple-sdlc`,
+  `content-generation`, `code-review`, `data-pipeline`,
+  `seo-review`, `api-builder`).
+- Asks any clarifying questions about your inputs, outputs, gates,
+  budgets, parallelism.
+- Writes a complete `.agentforge/` directory into your project root.
+
+---
+
+## 4. Run the pipeline the skill built
+
+You have two paths:
+
+**Path A — type the commands yourself** (the skill prints them when it
+finishes):
+
+```bash
+# Validate what got generated
+npx @mandarnilange/agentforge-core list
+
+# Run it (replace the brief with your real input)
+npx @mandarnilange/agentforge-core run \
+  --project my-first-run \
+  --input "brief=Build a freelance invoicing SaaS"
+
+# Watch the run live
+npx @mandarnilange/agentforge-core dashboard      # → http://localhost:3001
+```
+
+**Path B — let the `agentforge-cli` skill do it for you.** Just say:
+
+> *Run the pipeline for project `my-first-run` with the brief
+> "Build a freelance invoicing SaaS". Then start the dashboard.*
+
+The skill maps your ask to the right CLI command, confirms before
+spending money, and reports the run ID and dashboard URL when it's up.
+
+That's the full loop.
+
+---
+
+## What else you can do, conversationally
+
+The skills are designed to keep working with you across sessions. Some
+prompts that keep paying off:
+
+- **Add a new agent** — *"Add a security review agent after the
+  architect."* → creates a new agent file; existing ones untouched.
+- **Tweak an existing agent** — *"Update the analyst agent to use
+  `claude-haiku-4-5`."* → asks you to confirm per file before editing.
+- **Add parallelism** — *"Run the test generator and the code generator
+  in parallel."* → modifies the pipeline (with confirmation).
+- **Insert a gate** — *"I want to review before code generation
+  starts."* → adds a gate to the relevant phase.
+- **Approve / reject / revise a gate** — *"Approve the architect gate on
+  the SDLC run."* → fires `agentforge-cli` (with cost-aware confirmation
+  before approval).
+- **List, inspect, monitor** — *"Show me current pipeline runs."* /
+  *"Any pending gates?"* / *"What nodes are online?"* → `agentforge-cli`.
+- **Apply YAML to the platform** — *"Apply every YAML in `.agentforge/`
+  to the cluster."* → `agentforge-cli` with `apply -f`.
+- **Debug a run** — *"Why is pipeline `<run-id>` stuck at phase 2?"* →
+  fires `agentforge-debug` to triage.
+- **Ship a new template upstream** — *"Help me contribute a new template
+  for ML pipeline scaffolding."* → fires `agentforge-template-author`.
+
+---
+
+## Heads up
+
+By default the workflow skill **creates new files alongside existing
+ones** — it never silently overwrites your `.agentforge/`. To edit
+something that already exists, say *update / edit / modify / extend* (or
+name the file). The skill confirms each edit before writing. Full rules:
+[Modification policy](../skills/agentforge-workflow/SKILL.md#modification-policy).
diff --git a/skills/CHANGELOG.md b/skills/CHANGELOG.md
@@ -41,6 +41,15 @@ next install.
 
 - _add entries here as they merge_
 
+### 2026-05-02 (cli skill + ops surface)
+
+- **`agentforge-cli` 0.1.0** — initial release. Conversational interface
+  to the AgentForge CLI: maps natural-language asks ("run my pipeline",
+  "approve gate X", "show me logs") to commands, executes via the host
+  agent's shell, summarises output. Confirms before any cost-incurring
+  or state-mutating command. See
+  [`agentforge-cli/CHANGELOG.md`](agentforge-cli/CHANGELOG.md).
+
 ### 2026-05-02 (modification policy sweep)
 
 - **`agentforge-workflow` 0.2.0** — added a Modification policy:

diff --git a/skills/README.md b/skills/README.md
@@ -17,13 +17,20 @@ The Vercel skills CLI scans the repo's `skills/` directory and installs every sk
 npx skills add https://github.com/mandarnilange/agentforge/tree/main/skills/agentforge-workflow
 ```
 
+## New here? Use the quickstart
+
+The [Skill Quickstart](../docs/skill-quickstart.md) is a 5-minute,
+fill-in-the-blanks markdown you edit, paste into your AI agent, and run.
+It's the recommended path for anyone trying the skills for the first time.
+
 ## Available skills
 
 | Skill | Audience | What it does |
 |---|---|---|
 | [`agentforge-workflow`](./agentforge-workflow/SKILL.md) | End user | Walks through designing an AgentForge workflow — agents, pipeline, gates, loops, parallelism, wiring, nodes — and emits a complete `.agentforge/` directory. |
-| [`agentforge-template-author`](./agentforge-template-author/SKILL.md) | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. Scope check → package selection → manifest → tests → PR checklist. |
+| [`agentforge-cli`](./agentforge-cli/SKILL.md) | Operator | Conversational interface to the AgentForge CLI. *"Run my pipeline"*, *"approve gate X"*, *"show me logs"* → maps to commands, confirms cost / state changes, summarises output. |
 | [`agentforge-debug`](./agentforge-debug/SKILL.md) | Operator | Triages a stuck or failing pipeline run from symptom → state inspection → root-cause classification → fix path. |
+| [`agentforge-template-author`](./agentforge-template-author/SKILL.md) | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. Scope check → package selection → manifest → tests → PR checklist. |
 
 Versions, release notes, and the bump policy live in [`CHANGELOG.md`](./CHANGELOG.md).
 

diff --git a/skills/agentforge-cli/CHANGELOG.md b/skills/agentforge-cli/CHANGELOG.md
@@ -0,0 +1,25 @@
+# `agentforge-cli` changelog
+
+## 0.1.0 — 2026-05-02
+
+Initial release.
+
+- Conversational interface to the AgentForge CLI: maps natural-language
+  asks ("run my pipeline", "approve gate X", "show me logs", "apply
+  this YAML") to the right `agentforge` / `agentforge-core` command,
+  executes via the host agent's shell, and summarises the output.
+- Read-first / confirm-before-mutate discipline: read-only commands
+  (`list`, `info`, `templates list`, `get *`, `describe node`, `logs`,
+  `dashboard` start) execute immediately; cost-incurring or
+  state-mutating commands (`run`, `run --continue`, `exec`, `gate
+  {approve,reject,revise}`, `apply`, `node start`) require explicit
+  confirmation via `AskUserQuestion` or equivalent, with cost ceiling
+  surfaced when visible from agent budgets.
+- Reference docs cover the natural-language → command map (sourced from
+  `packages/{core,platform}/src/cli/commands/`), confirmation rules
+  with example prompts, and output-summary patterns (3–5 line summaries,
+  no raw table dumps unless explicitly asked).
+- Hard rules: never run state-mutating commands without confirmation;
+  never silently disambiguate between matching resources; never invent
+  flags; always show the command before running it; background long-
+  running commands like `dashboard` and `node start`.