Skip to content

feat(skills): skill quickstart + agentforge-cli (conversational ops surface)#13

Merged
mandarnilange merged 3 commits intomainfrom
feat/skill-quickstart
May 2, 2026
Merged

feat(skills): skill quickstart + agentforge-cli (conversational ops surface)#13
mandarnilange merged 3 commits intomainfrom
feat/skill-quickstart

Conversation

@mandarnilange
Copy link
Copy Markdown
Owner

Summary

Two related additions for first-time and day-2 users:

1. Skill Quickstart — docs/skill-quickstart.md

A 4-step, fill-in-the-blanks markdown for users new to the skills. No
YAML, no scaffolding by hand — just:

  1. Install the skill (npm install @mandarnilange/agentforge-core,
    npx skills add mandarnilange/agentforge)
  2. Open your AI coding agent (Claude Code / Cursor / Codex / Aider /
    Continue.dev — same flow for all)
  3. Tell the skill what you want — four sample prompts (Classic SDLC,
    Content generation, Code review, Something new)
  4. Run the pipeline the skill built — either type the commands yourself
    or let `agentforge-cli` do it for you

Day-2 follow-up prompts shown inline so users see the full surface,
not just day 1. Pitched at the `@mandarnilange/agentforge-core` install
path since that's the primary user audience.

2. New skill — `agentforge-cli` (0.1.0)

Conversational interface to the AgentForge CLI. Maps natural-language
asks to the right command, executes via the host agent's shell, and
summarises the output instead of dumping raw tables.

User says Skill runs
"Run my pipeline for project X" ` run --project X --input ...`
"Approve the architect gate" ` gate approve `
"Show me current pipeline runs" ` get pipelines` (read-only)
"Show me logs for run Y" ` logs Y`
"Apply this YAML to the cluster" ` apply -f ...`
"Start the dashboard" ` dashboard` (backgrounded)

Discipline matches the rest of the family:

  • Read-first / confirm-before-mutate. Read-only commands
    (`list`, `info`, `templates list`, `get *`, `describe node`,
    `logs`, `dashboard` start) execute immediately. State-mutating or
    cost-incurring 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.
  • Never invent flags. Every flag in `references/command-map.md` is
    sourced from `packages/{core,platform}/src/cli/commands/` verbatim.
  • Long-running commands backgrounded. `dashboard` and `node
    start` don't block the conversation.
  • Human summaries by default. 3–5 line "what state is in, what to do
    next" instead of raw tables.

Skill family is now four:

Skill Audience Role
`agentforge-workflow` End user Design (writes `.agentforge/`)
`agentforge-cli` Operator Operate (run, monitor, manage) — new
`agentforge-debug` Operator Triage (stuck/failing runs)
`agentforge-template-author` Contributor Contribute upstream

Same install command picks them all up:

```bash
npx skills add mandarnilange/agentforge
```

Versioning

Per the bump policy in `skills/CHANGELOG.md`, only `agentforge-cli` is
new (0.1.0). The other three skills had zero changes to their
`SKILL.md` or `references/` directories on this branch — repo-level
docs (`README.md`, top-level `skills/CHANGELOG.md`, quickstart) don't
trigger a per-skill bump.

Skill Version Reason
`agentforge-workflow` 0.2.0 (unchanged) Skill payload unchanged
`agentforge-cli` 0.1.0 (new) Initial release
`agentforge-debug` 0.2.0 (unchanged) Skill payload unchanged
`agentforge-template-author` 0.2.0 (unchanged) Skill payload unchanged

Test plan

  • `npm run skills:validate` — all four skills frontmatter-valid;
    CI Publish Skills workflow should turn green.
  • `npx biome check .` clean.
  • All 11 doc links in the README's Learn more section resolve
    (the new `docs/skill-quickstart.md` is added there too).
  • Manual validation in a fresh coding-agent session:
    • Quickstart flow end-to-end: install → open editor → paste a
      sample brief → confirm `agentforge-workflow` fires and emits
      `.agentforge/`.
    • `agentforge-cli` happy path: "Run my pipeline for project
      X"
      → confirm prompt with cost ceiling → execution → summary.
    • `agentforge-cli` confirmation hold: respond "no" to a
      `run` confirmation → no command runs.
    • Disambiguation: "approve the gate" with two pending gates →
      skill lists both and asks which.

…users

A small editable markdown the user edits in place — fills in goal /
inputs / constraints / starting point — and pastes into their AI agent
to fire agentforge-workflow. Targets agentforge-core users who will
typically drop a shared default .agentforge/ folder into their project
and customize from there.

Linked from the README's Agent Skills section and the Get-started
track of the Learn-more index, plus a top-of-page pointer in
skills/README.md.
Drops the bracketed brief template and the .agentforge starter
section. Replaces with a plain four-step flow: install skill → open
your AI coding agent → describe what you want (with four sample
prompts spanning SDLC / content / code review / something new) → run
the commands the skill prints.

Adds a "what else you can do" section with conversational follow-up
prompts (add agent, tweak agent, add parallelism, insert gate, debug,
contribute template) so users see the day-2 surface, not just day 1.

Pitched at the @mandarnilange/agentforge-core install path since
that's the primary user audience.
Fourth skill in the family. Maps natural-language operational asks
("run my pipeline", "approve gate X", "show me logs", "apply this
YAML", "list pending gates") to the right agentforge / agentforge-core
command, executes via the host agent's shell, and summarises the
output instead of dumping raw tables.

Discipline matches the rest of the family:

- Read-first / confirm-before-mutate. Read-only commands (list, info,
  templates list, get *, describe node, logs, dashboard start) execute
  immediately. State-mutating or cost-incurring 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.
- Never invent flags — the command map is sourced from
  packages/{core,platform}/src/cli/commands/ verbatim.
- Long-running commands (dashboard, node start) backgrounded so they
  don't block the conversation.
- Human-readable summaries by default; raw tables only when explicitly
  requested.

Skill family is now: workflow (design) + cli (operate) + debug
(triage) + template-author (contribute upstream). Same install
command picks up the new skill automatically:

  npx skills add mandarnilange/agentforge

Quickstart, README's Agent Skills table, and skills/README.md updated
to surface the new skill alongside the existing three.
@mandarnilange mandarnilange merged commit d77f34d into main May 2, 2026
5 checks passed
@mandarnilange mandarnilange deleted the feat/skill-quickstart branch May 2, 2026 06:43
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