Agent and Skills Guide
Essential knowledge
Intended Audience:
Technical User
Author:
Fluent Commerce
Changed on:
1 Apr 2026
Overview
This purpose of this guide is to explain the runtime model for the`@fluentcommerce/ai-skills` package by detailing its 6 agents and over 60 registered skills. This will also act as a practical reference manual to help developers understand exactly which agent handles what, which specific skills to invoke, and where those skills fit into the software development lifecycle (SDLC).Key points
- How to route tasks to the correct agents: learn which agents own specific front end/back end tasks
- How to apply skills across the SDLC (Software Development Lifecycle)
- How to troubleshoot and operate the system
- When to use natural language vs slash commands: Use natural language when focusing on outcomes vs specific slash commands when precise control is needed
See
This is the fastest way to understand the runtime model for
If the agent or skill inventory changes, update this guide together with:
`../README.md` for the full disclaimer.This is the fastest way to understand the runtime model for
`@fluentcommerce/ai-skills`:- which agent handles what
- which skill to invoke
- when to invoke it
- where it fits in the SDLC
`metadata.json`.- Start with natural language when you are outcome-focused. Example: "Explain how Home Delivery works" or "Add a page to the OMS manifest".
- Use a slash command when you know the exact skill you want. Example:
`/fluent-feature-plan`,`/fluent-workflow-builder`,`/fluent-ui-test`. - Treat agents as routers, not as commands. Agents are selected automatically from intent. In normal use, you do not manually invoke
`fluent-dev`or`fluent-backend-dev`. - Use package CLI commands for installation and platform wiring, not feature delivery. Example:
`npx @fluentcommerce/ai-skills install`,`status`,`uninstall`,`mcp-setup`.
- Use natural language first if you are not sure which skill is correct.
- Use slash commands when you want precise control.
- Read-only skills are usually safe at any time: status, explain, analyze, validate, trace, review, reference.
- Build, scaffold, deploy, rollback, and environment-changing skills usually sit behind planning or approval gates.
- Slash commands are Claude Code friendly. Natural-language routing is the safer default across tools.
| Document | Best for |
`INDEX.md` | Docs hub and reading order |
`../README.md` | Install, package overview, top-level architecture |
`docs/05-getting-started.md` | Setup reference and troubleshooting |
`docs/03-use-cases.md` | Example prompts and expected outcomes |
`docs/capability-map.md` | Capability ownership backstop and maintainer reference |
`docs/fluent-ai-skills-reference.md` | Deep operational reference |
`docs/06-dev-workflow.md` | End-to-end autonomous delivery loop |
| Agent | Group | Auto-route when | What it owns | Good starting skills |
`fluent-dev` | `dev` | The request spans frontend and backend, or you need planning, explain, mapping, status, or E2E coordination | Cross-cutting lifecycle orchestration | `/fluent-use-case-discover`, `/fluent-feature-plan`, `/fluent-feature-explain`, `/fluent-feature-status`, `/fluent-e2e-test` |
`fluent-backend-dev` | `dev` | The request mentions workflows, rules, rule tests, modules, settings, events, tracing, Java, Maven, or deployment | Backend implementation and runtime operations | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-rule-test`, `/fluent-module-scaffold`, `/fluent-build`, `/fluent-trace`, `/fluent-entity-flow-diagnose` |
`fluent-frontend-dev` | `dev` | The request mentions manifests, pages, routes, components, Mystique, SDK projects, frontend build, or browser UI verification | Frontend implementation and UI verification | `/fluent-mystique-builder`, `/fluent-mystique-scaffold`, `/fluent-frontend-build`, `/fluent-ui-test`, `/fluent-frontend-review` |
`fluent-cli` | `cli` | The request is really about Fluent CLI commands, profiles, retailers, workflow download/listing, or module install operations | CLI family routing and command guidance | `/fluent-connect`, `/fluent-profile`, `/fluent-cli-retailer`, `/fluent-module-deploy`, `/fluent-workflow` |
`fluent-mcp` | `mcp-extn` | The request is about MCP servers (extension or official CLI), workflow download/list, GraphQL build/validate, events, batch, entities, metrics, or webhook validation | MCP tool usage, payload contracts, and core GraphQL/workflow utilities | `/fluent-mcp-tools`, `/fluent-mcp-core` |
`fluent-rfl` | `rfl` | The request is a production-readiness or go-live audit | Readiness assessment and risk reporting | `/fluent-rfl-assess` |
| Stage | Goal | Start here |
| Environment setup | Get the workspace, profile, retailer, and MCP wiring ready | `/fluent-bootstrap`, `/fluent-connect`, `/fluent-profile`, `/fluent-cli-mcp-cicd` |
| Discover current state | Understand what already exists before changing anything | `/fluent-implementation-map`, `/fluent-feature-explain`, `/fluent-workflow-analyzer`, `/fluent-mystique-assess`, `/fluent-feature-status`, `/fluent-account-snapshot` |
| Requirements | Turn business need into an approved spec | `/fluent-use-case-discover` |
| Phasing | Split a large approved feature into vertical slices | `/fluent-scope-plan` |
| Technical planning | Produce the implementation contract for multi-artifact work | `/fluent-feature-plan` |
| Backend implementation | Change workflows, rules, rule tests, modules, settings, or environment config | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-rule-test`, `/fluent-module-scaffold`, `/fluent-settings` |
| Frontend implementation | Change manifests, SDK components, frontend build/test assets | `/fluent-mystique-builder`, `/fluent-mystique-scaffold`, `/fluent-mystique-component`, `/fluent-frontend-build` |
| Validate and build | Run structural, code, and pre-deploy quality gates | `/fluent-module-validate`, `/fluent-mystique-assess`, `/fluent-frontend-review`, `/fluent-pre-deploy-check`, `/fluent-build` |
| Deploy | Push module, workflow, or settings changes | `/fluent-module-deploy`, `/fluent-workflow-deploy`, `/fluent-settings` |
| Test and verify | Confirm behavior in API, workflow, and browser layers | `/fluent-test-data`, `/fluent-e2e-test`, `/fluent-transition-api`, `/fluent-ui-test` |
| Diagnose and recover | Trace failures, compare runtime vs workflow intent, monitor health, or roll back safely | `/fluent-trace`, `/fluent-entity-flow-diagnose`, `/fluent-system-monitoring`, `/fluent-connection-analysis`, `/fluent-rollback` |
| Audit and wrap-up | Summarize, assess readiness, export audit trail, or archive | `/fluent-rfl-assess`, `/fluent-session`, `/fluent-archive`, `/fluent-skill-observability` |
1. Setup and Platform Access
| Skill | What it does | Invoke when |
`/fluent-bootstrap` | Creates a new Fluent account workspace end-to-end: profile, retailer, modules, and initial setup | You are starting from a brand-new account or environment |
`/fluent-connect` | Connects an existing account, wires MCP, downloads workflows, scans source, and prepares the workspace | You are starting work in an existing tenant or switching into a prepared workspace |
`/fluent-profile` | Manages Fluent CLI profiles | Credentials, account context, or active profile need to change |
`/fluent-cli-retailer` | Lists or creates retailers and validates retailer CLI context | Retailer admin or environment setup is the task |
`/fluent-cli-reference` | Provides exact Fluent CLI command and flag reference, and routes broad CLI questions | You need command syntax, flags, or examples, or the request mixes profiles, retailers, workflows, modules, and settings |
`/fluent-cli-mcp-cicd` | Sets up the CLI MCP server and CI/CD-safe automation patterns | You are wiring MCP or building deployment automation |
`/fluent-mcp-core` | Covers official CLI MCP setup plus GraphQL build, validate, execute, and workflow list/download | You want built-in MCP server workflows and GraphQL utilities (now under `mcp-extn` group) |
`/fluent-mcp-tools` | Documents the extension MCP tool contracts for events, GraphQL, entities, metrics, workflows, batch, and cache | You need exact MCP payload shape, limits, or tool selection |
2. Discovery, Documentation, and Planning
| Skill | What it does | Invoke when |
`/fluent-account-snapshot` | Produces a lightweight account state inventory — retailers, workflows, modules, catalogues, settings, UI customizations | You want a quick overview of what exists in the account |
`/fluent-workspace-tree` | Shows an annotated workspace tree with artifact counts and status overlays | You need to orient yourself in the account workspace |
`/fluent-feature-status` | Shows the current feature lifecycle table, next actions, and generates the live feature dashboard | You want to know what is in progress, blocked, or ready next, or you want a browser view of feature artifacts and status |
`/fluent-implementation-map` | Reverse-engineers the account into a feature inventory and dependency map | You need a broad picture of what has been built |
`/fluent-feature-explain` | Produces an architecture-style explanation of an existing feature | The question is "how does this work?" rather than "change it" |
`/fluent-use-case-discover` | Turns vague requirements, notes, or a PRD into a structured business spec | You are starting a new feature and the business shape is not locked yet |
`/fluent-scope-plan` | Breaks features into phases and converts scope documents into ordered tasks and dependencies | The feature is too large for one plan-build-deploy cycle, or you have a scope pack and need executable work items |
`/fluent-feature-plan` | Produces the technical implementation contract across artifacts | The work spans multiple artifacts such as rules, workflows, settings, and UI |
`/fluent-goal` | Goal-oriented task tracking with deadlines and progress | You have a delivery target and want the AI to track progress toward it |
`/fluent-knowledge-init` | Captures account-specific conventions, business rules, integrations, and test context | You want reusable project knowledge in the workspace |
`/fluent-archive` | Archives a completed or abandoned feature and performs lifecycle cleanup | The feature is done and should be formally closed out |
3. Backend Delivery
| Skill | What it does | Invoke when |
`/fluent-workflow` | Handles operational workflow CLI tasks such as list, download, merge, and workflow logs | You need workflow files or workflow CLI operations rather than design logic |
`/fluent-workflow-builder` | Creates or edits workflow JSON definitions, rulesets, statuses, and triggers | You are implementing or changing workflow behavior |
`/fluent-workflow-analyzer` | Validates and analyzes workflow JSON — status graphs, event chains, orphaned rulesets, trigger coverage, and structural correctness | You want to understand, validate, or audit a workflow before or after change |
`/fluent-workflow-deploy` | Deploys standalone workflow JSON with strict preflight and fallback paths | You need to ship workflow-only changes safely |
`/fluent-rule-scaffold` | Generates a new Java rule and test and wires it into the module manifest | New custom backend rule logic is required |
`/fluent-rule-test` | Generates or repairs backend rule tests using the repo's local harness conventions | A rule already exists and you need to add, fix, or backfill its tests |
`/fluent-rule-lookup` | Finds rules by name, annotation, or behavior across deployed modules and source code | You need to locate a rule, check what rules use a particular annotation, or audit rule coverage |
`/fluent-module-scaffold` | Creates a new Java/Maven Fluent extension module | You need a new plugin module rather than adding to an existing one |
`/fluent-data-module-scaffold` | Creates a data-only module with assets and build scripts but no Java plugins | You need a module for workflows, settings, or data assets only |
`/fluent-module-validate` | Validates module structure, contents, and classification | You want to check a module before build or deploy, or audit what exists |
`/fluent-build` | Builds and packages Fluent extension modules; also handles version reads, bumps, and sync | Source changes are ready to compile and package, or you need to prepare or align a release version |
`/fluent-module-convert` | Restructures non-standard or decompiled code into Fluent module format | You have code that does not yet match Fluent module conventions |
`/fluent-settings` | Discovers, audits, creates, updates, and migrates settings | Behavior depends on settings or settings need to be deployed |
`/fluent-retailer-config` | Creates and configures environment entities such as locations, networks, carriers, and catalogues | You are doing retailer environment setup or cloning |
`/fluent-inventory-catalog` | Manages virtual inventory catalogues, positions, segments, and control groups | The work is specifically about virtual inventory structures |
`/fluent-sourcing` | Provides the Responsive Sourcing Framework reference and operational patterns | You are designing or debugging sourcing and fulfilment allocation logic |
`/fluent-custom-code` | Analyzes existing custom backend code and produces reusable artifacts | You need to understand source-level behavior before changing it |
`/fluent-module-deploy` | Installs module ZIPs into target retailers | You are ready to deploy modules, bundled settings, or bundled workflow changes |
4. Frontend Delivery
| Skill | What it does | Invoke when |
`/fluent-mystique-sdk-reference` | Serves as the SDK and registry reference for Mystique component development | You need exact hook, registry, or SDK usage patterns before coding |
`/fluent-mystique-builder` | Creates or edits Mystique manifests, routes, pages, and components | The UI change can be solved with manifest configuration |
`/fluent-mystique-assess` | Validates and analyzes manifest schema, components, queries, complexity, usage patterns, and architectural health | You need to verify a manifest before deployment, or you are auditing or reverse-engineering an existing frontend |
`/fluent-mystique-diff` | Compares customized manifests against deployed or baseline state | You need to know what changed or what is overridden |
`/fluent-mystique-preview` | Previews likely UI changes before a real deployment | You want fast visual iteration on layout or structure |
`/fluent-mystique-scaffold` | Scaffolds a brand-new Mystique SDK project | Configuration is not enough and a custom bundle is needed |
`/fluent-mystique-component` | Adds a component, field, or template helper to an existing SDK project | You already have a bundle and want to extend it |
`/fluent-frontend-build` | Runs local dev mode or full production frontend build gates | You need hot reload locally or a deployable SDK bundle |
`/fluent-frontend-review` | Performs a read-only audit of SDK code quality, GraphQL, docs, and readiness | You want a release-quality frontend review before shipping |
`/fluent-frontend-readme` | Generates or refreshes project README documentation from source | You need handover-quality docs for an SDK project |
`/fluent-ui-test` | Verifies deployed UI behavior in OMS or Store via browser automation | You need to prove the UI renders and behaves correctly in the real app |
`/fluent-ui-record` | Captures annotated walkthroughs and before/after evidence | You need screenshots, walkthrough evidence, or reporting artifacts |
5. Test, Diagnose, and Operate
| Skill | What it does | Invoke when |
`/fluent-test-data` | Discovers live references and creates valid test entities dynamically | Tests need real environment-compatible data without hardcoding |
`/fluent-e2e-test` | Runs end-to-end scenarios and asserts state transitions | You want post-deploy functional verification across the workflow lifecycle |
`/fluent-transition-api` | Discovers available user actions at a given status | You are validating UI buttons, action visibility, or dynamic user action paths |
`/fluent-event-api` | Explains the event model, statuses, filters, and event contracts | The question is about event semantics or event query strategy |
`/fluent-trace` | Traces failed processing and surfaces runtime root cause | An entity is stuck, an event failed, or the runtime story is unclear |
`/fluent-entity-flow-diagnose` | Reconstructs the entity event chain and compares runtime against workflow intent | You have a real entity ref and want the complete expected-vs-observed diagnosis |
`/fluent-system-monitoring` | Monitors metrics, failure rates, latency, and event health | You are doing observability, triage, or health monitoring |
`/fluent-connection-analysis` | Maps cross-entity and cross-workflow topology and conformance | Dependencies, setting linkage, or runtime-vs-static drift need analysis |
`/fluent-job-batch` | Monitors and explains JOB and BATCH entity lifecycles | The work centers on batch ingestion or async job processing |
`/fluent-pre-deploy-check` | Runs pre-deployment quality gates across module, workflow, environment, and settings | You need a final go or no-go decision before deployment |
`/fluent-rollback` | Performs guided rollback for workflows, modules, or settings | A deployment must be reversed safely |
`/fluent-rfl-assess` | Audits production readiness for go-live | You need a launch-readiness or release-readiness review |
6. Session, Audit, and Quality Loop
| Skill | What it does | Invoke when |
`/fluent-session` | Summarizes what changed in the current session in human-readable form; use `/fluent-session export` for a machine-readable JSON audit trail | You want a wrap-up, handover, decision chain summary, or structured audit export for CI/CD and compliance |
`/fluent-skill-observability` | Traces skill routing, generates routing reports, and captures feedback on skill performance | You want to understand which skill handled a request, review routing decisions, or tune skill quality |
| If the user says... | Start with |
| "Help me set this workspace up" | `/fluent-connect` |
| "We have an idea but need requirements" | `/fluent-use-case-discover` |
| "Plan this feature" | `/fluent-feature-plan` |
| "Explain what already exists" | `/fluent-feature-explain` or `/fluent-implementation-map` |
| "Change workflow behavior" | `/fluent-workflow-builder` |
| "Add a custom rule" | `/fluent-rule-scaffold` |
| "Write or fix a rule test" | `/fluent-rule-test` |
| "Create a module" | `/fluent-module-scaffold` or `/fluent-data-module-scaffold` |
| "Build or deploy this backend change" | `/fluent-build`, then `/fluent-module-deploy` or `/fluent-workflow-deploy` |
| "Change the UI" | `/fluent-mystique-builder` or `/fluent-mystique-scaffold` |
| "Test in browser" | `/fluent-ui-test` |
| "Why did this fail?" | `/fluent-trace` |
| "Show me what happened vs what should have happened for this entity" | `/fluent-entity-flow-diagnose` |
| "Is this safe to ship?" | `/fluent-pre-deploy-check` or `/fluent-rfl-assess` |
`metadata.json``README.md``docs/capability-map.md``docs/fluent-ai-skills-reference.md`
