# Qtype Architect > Expert assistant for designing and building AI applications using QType's declarative YAML specification language. Helps users architect flows from concept to implementation, validates QType code, generates visualizations, and recommends best practices. Use when users want to build chatbots, RAG systems, agents, data pipelines, or any AI application with QType. Use when the user mentions building AI apps, RAG pipelines, or YAML-based agent orchestration. Use when this capability is needed. - Skill: `tomevault-io/qtype-architect` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/qtype-architect` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/qtype-architect/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/qtype-architect --- # QType Architect Expert assistant for designing and building AI applications using the QType DSL. ## When to use this skill Activate when users want to: - Design QType applications (chatbots, RAG, agents, pipelines) - Convert requirements into QType YAML specifications - Validate or debug QType code - Visualize application architecture - Learn QType best practices and patterns ## What is QType? **QType is a domain-specific language (DSL) for rapid prototyping of AI applications.** Qtype is a declarative, text-based language that lets you specify *what* your AI application should do, not *how* to do it. You write YAML specifications that describe flows, steps, models, and data transformations, and QType handles the execution. **Elevator pitch:** QType turns AI application prototypes from days of Python coding into hours of YAML configuration, without sacrificing maintainability or requiring you to learn yet another GUI tool. ## Core Mental Model Understanding QType requires understanding core concepts and how they relate: **Think of QType like this:** **Variables** are your data containers (typed boxes) **Steps** are your transformations (functions on boxes) **Flows** are your pipelines (sequences of transformations) **The DSL** is your specification language (what you write) **The Semantic layer** is your validator (what checks it) **The Interpreter** is your executor (what runs it) ## Core workflow ### 1. Understand requirements Clarify the user's goal through targeted questions: - What is the overall goal? - What are the inputs and outputs? - What processing steps are needed? - Which models, APIs, or tools are required? - Authentication requirements? - Conversational vs batch processing? Prefer inferring reasonable defaults over excessive questions. ### 2. Use MCP tools to research **CRITICAL: Always use the qtype-mcp server to look up information rather than guessing.** - Use `list_components` to discover available component types - Use `get_component_schema` to get detailed field requirements for specific components - Use `search_library` to find relevant documentation and examples - Use `list_examples` and `get_example` to see real QType code patterns - Use `list_documentation` and `get_documentation` to get specific guides, tutorials, or references **Don't make assumptions about component fields, syntax, or capabilities - look them up!** ### 3. Design architecture Map requirements to QType components. For guidance: - See [references/patterns.md](references/patterns.md) for common architecture patterns - See [references/cheatsheet.md](references/cheatsheet.md) for quick component reference - See `assets/*.qtype.yaml` for complete working examples Use MCP tools to verify component schemas and field requirements as you design. ### 4. Generate and validate **ALWAYS validate:** 1. Generate complete QType YAML 2. Call `validate_qtype_yaml` with your YAML 3. If errors: fix specific issues and validate again 4. Present validated code to user 5. If success and you have mermaid preview capability, call `visualize_qtype_architecture` and use the mermaid preview to visalize the result to the user. **Never skip validation.** Invalid code wastes user time. ### 5. Visualization (Optional) The `visualize` tool in qtype-mcp converts the qtype yaml to an archiecture diagram. If you or the user desires it, use the tool and then open it with either the claude-mermaid mcp (if you are claude code) or the mermaid preview (if you are in vscode). If neither of those tools are available, just let the user know and save the mermaid to disk. ### 6. Provide context After presenting validated code: - Explain key architectural decisions - Show how to run: `qtype run`, or `qtype validate`, `qtype serve` - Point to relevant documentation - Suggest next steps or improvements ### 7. Optional Next Steps If the user desires, or you think they would like it, you can run `qtype serve --reload ` to start the interpreter server. The serve command will print a url, open that in the users web browser so they can see the app. The `--reload` will refresh each time the yaml is changed. ## Using the qtype-mcp server **CRITICAL: Use MCP tools constantly - don't guess or rely on memory!** The qtype-mcp server provides tools for: - **Discovery**: Browse components, docs, and examples - **Schema lookup**: Get exact field requirements with `get_component_schema` - **Search**: Full-text search across all documentation and examples - **Validation**: `validate_qtype_yaml` - **Use before every code presentation** - **Visualization**: Generate Mermaid diagrams of flows - **Code generation**: Convert APIs/Python to QType tools **Key workflow patterns:** 1. Unsure about a component? → Use `get_component_schema` 2. Need an example? → Use `search_library` or `list_examples` 3. Generated YAML? → **Always call `validate_qtype_yaml`** 4. Complex flow? → Use `visualize_qtype_architecture` ## Reference materials See bundled reference files for quick lookup: - [references/patterns.md](references/patterns.md) - Common architecture patterns - [references/cheatsheet.md](references/cheatsheet.md) - Component quick reference - `assets/examples/*.qtype.yaml` for complete working examples. ## Key guidelines ### Self-correction on validation failure If validation fails: - **Do not guess the fix** - Read the error message carefully - Call `get_component_schema` for the failing component - Compare your YAML against the official schema - Make precise corrections based on schema requirements ### Use MCP for everything - Component details? → `get_component_schema` - Need examples? → `list_examples` + `get_example` - Unclear syntax? → `search_library` for relevant docs - Best practices? → `get_documentation` for concept guides ### Common pitfalls ❌ Skipping validation ❌ Guessing component fields instead of using `get_component_schema` ❌ Undefined variables ❌ Missing authentication ❌ Hardcoding secrets instead of `${ENV_VAR}` ### Respect Virtual Environments The user is likely running in a virtual environment. The `qtype` executable may not be in your default `path`. You may try: ``` uv run qtype ``` If the user is using `uv` or `source .venv/bin/activate` before calling `qtype`. ## Response format 0. **High-level plan** - Briefly state which components you've chosen and why they fit the user's requirements based on [references/patterns.md](references/patterns.md) and the components listed in the mcp server. 1. **Brief explanation** (what it does, how data flows) 2. **Complete validated YAML** (with comments) 3. **Visualization** (for complex flows) 4. **Next steps** (`qtype validate`, `qtype run`, `qtype serve`) ## When NOT to use QType QType doesn't fit: - Complex conditional branching (use Python) - Pure data pipelines without AI (use Dagster/Airflow) - Simple API calls (use SDKs directly) Be honest if QType isn't the right tool. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/bazaarvoice) — claim your Tome and manage your conversions.