Agent and Skills Guide
Essential knowledge
Intended Audience:
Technical User
Authors:
Marco Heuer, 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
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`
