Skip to main content

AI-Assisted Development

Overview​

The @axinom/mosaic-agent-skills package is an MCP (Model Context Protocol) server that provides AI-powered code generation capabilities for Mosaic development. It bundles specialized skills for generating frontend stations along with comprehensive GraphQL schema inspection tools.

What's Included​

Frontend Station Generation Skills:

  • Generate Explorer Station - Creates entity browsing interfaces with lists, filters, sorting, pagination, real-time updates, bulk-edit, and quick edit integration
  • Generate Create Station - Generates entity creation forms with validation
  • Generate Details Station - Builds entity editing forms with update/delete actions, image/video management, and resource management

MCP Tools:

  • Skills Management Tools: These are a set of tools that will allow any LLM Model that understands tool calling to function with the Mosaic Agent Skills
  • GraphQL Schema Tools: These are a set of tools that helps speed up GQL schema introspection for the skills/references

Design Philosophy​

The Mosaic Agent Skills package is designed with several key principles:

1. AI Agent Agnostic​

The skills work with any AI agent that supports the Model Context Protocol (MCP), not just Claude. This includes:

  • VS Code with GitHub Copilot
  • Claude Code (CLI)
  • Other MCP-enabled AI agents

By building on MCP rather than agent-specific APIs, we ensure that different development teams can use their preferred AI tools while still benefiting from Mosaic's code generation capabilities.

2. Self-Contained Skills​

Each skill is completely self-contained with:

  • All conventions and naming patterns defined within the skill
  • Code templates and reference files packaged together
  • Step-by-step workflows that mimic actual developer thought processes
  • Domain and repository agnostic design

The skills discover your project structure and adapt to your GraphQL schema, making them work across different Mosaic projects without modification. As long as your project uses the Mosaic stack, the skills will work.

3. Reliable, Repeatable Outputs​

We've implemented techniques to ensure consistent code generation across different AI models:

  • Structured EntityFeatures extraction - Uses MCP tools to parse GraphQL schemas and compute a strict, structured representation of entity features
  • Schema-driven generation - The EntityFeatures object serves as the single source of truth for all generation steps
  • Step-by-step workflows - Breaking down complex tasks into discrete steps improves reliability across models

4. Learning by Example​

The skills can serve a dual purpose:

  • For AI agents - Automated code generation following Mosaic best practices
  • For developers - A learning tool demonstrating how to build Mosaic stations step-by-step

By examining the skill workflows and generated code, developers can understand Mosaic patterns and apply them manually when needed. In a way, these skills can even be used as learning tools for self-awareness, allowing developers to understand how to generate relevant artifacts thoughtfully and make informed adjustments.

Configuration​

The Mosaic Agent Skills package runs as an MCP server that AI agents connect to. You configure your AI agent to use npx @axinom/mosaic-agent-skills, which automatically downloads and runs the latest version without requiring a separate installation step.

VS Code with GitHub Copilot​

Add to your VS Code settings (.vscode/mcp.json in your workspace or user settings):

{
  "servers": {
    "mosaic-agent-skills": {
      "type": "stdio",
      "command": "npx",
      "args": ["@axinom/mosaic-agent-skills"]
    }
  }
}

Claude Code​

Add this configuration block to your Claude Code settings:

Configuration file location:

  • Linux/macOS: ~/.config/claude-code/config.json
  • Windows: %APPDATA%\claude-code\config.json
{
  "mcpServers": {
    "mosaic-agent-skills": {
      "type": "stdio",
      "command": "npx",
      "args": ["@axinom/mosaic-agent-skills"]
    }
  }
}

After adding the configuration, restart Claude Code for the changes to take effect.

Other MCP-Enabled Agents​

For other AI agents that support MCP, refer to their specific documentation for MCP server configuration. The general pattern is:

{
  "mcpServers": {
    "mosaic-agent-skills": {
      "type": "stdio",
      "command": "npx",
      "args": ["@axinom/mosaic-agent-skills"]
    }
  }
}

Usage​

Prerequisites​

Before using the skills, ensure you have:

  1. A Mosaic project set up (e.g., from the Mosaic Media Template)
  2. The MCP server configured in your AI agent

Basic Prompts​

Use these simple prompts to generate stations individually:

Generate an Explorer Station​

using the mosaic-agent-skills, generate an explorer station for the entity {YOUR_ENTITY_NAME}.

Generate a Create Station​

using the mosaic-agent-skills, generate a create station for the entity {YOUR_ENTITY_NAME}.

Generate a Details Station​

using the mosaic-agent-skills, generate a details station for the entity {YOUR_ENTITY_NAME}.

What Happens During Generation​

When you invoke a skill, the AI agent will:

  1. Discover your project structure - Finds schema paths, Apollo client, generated types locations
  2. Extract entity features - Analyzes your GraphQL schema to understand the entity structure
  3. Generate code artifacts - Creates all necessary files (GraphQL operations, TypeScript components, utilities)
  4. Run codegen - Generates TypeScript types from GraphQL operations
  5. Validate TypeScript - Runs tsc to verify compilation
  6. Register stations - Updates route registrations and navigation
  7. Print summary - Shows all generated files and remaining TODOs

Each step mimics the actual development thought process an engineer would follow, making the generation process transparent and educational.

Typical Execution Times (with Claude Sonnet 4.5):

  • Explorer Station: ~10 minutes
  • Create Station: ~5 minutes
  • Details Station: ~10 minutes

These times include all steps above. Actual times may vary depending on entity complexity and AI model used.

Advanced Usage: Parallel Generation​

If your AI agent supports sub-agents (like Claude Code), you can parallelize the generation of multiple stations:

using the mosaic-agent-skills MCP tools, generate me the explorer, create & details stations for the entity AudioBook.

you should delegate tasks to sub-agents and do things in parallel

be mindful that there are some common steps involved with the generation - so you should optimize and reuse the same knowledge by spending time/tokens only once

This approach:

  • Generates all three stations simultaneously
  • Reuses common analysis (project discovery, entity feature extraction)
  • Reduces total generation time and token consumption
  • Depends on the AI agent's sub-agent capabilities

Note: This advanced usage depends on your AI agent's capabilities. Claude Code supports this pattern well, while other agents may not and could potentially run into problems.

Video Demonstration​

Watch a demonstration showing all three skills being used to generate complete entity management functionality:

Known Limitations​

Version Alignment​

The skills generate code compatible with the latest @axinom/mosaic-ui library interfaces. There is currently no versioning support.

If you're using an older version of @axinom/mosaic-ui:

  • The generated code may use newer interfaces
  • Most AI models will adapt and fix interface mismatches automatically
  • This may consume additional time and tokens
  • Consider upgrading to the latest Mosaic version for best results

Model Performance​

While the skills work across models, reliability varies:

  • Best: Claude Sonnet 4.5 - Most consistent, follows patterns precisely
  • Good: Gemini 3 Pro, GPT 5.1 Codex - Reasonable results, may need minor adjustments
  • Experimental: Other models - May work but not extensively tested

Feel free to test with your preferred model and AI agent combination. We welcome feedback on what works well for your setup.

More to Come​

The Mosaic Core team is actively expanding the agent skills ecosystem:

New Skills​

  • Brownfield Skills - Update and extend existing stations
  • Backend Skills - Generate database migrations, add core features such as BulkEdit

Extensibility​

Possibilities to create project-specific skills. This will allow teams to build their own domain-specific skills that capture project-specific patterns and conventions.

Customizability​

Ability to tweak core skills for project-specific needs. Teams will be able to adapt the core skills to match their specific coding standards and architectural decisions.

Better Evaluation​

As the industry matures, we're working on standardized testing and evaluation of skill performance.

Best Practices​

  1. Start with Explorer - Generate the explorer first to establish routing and navigation
  2. Review Generated Code - While reliable, always review and understand what was generated
  3. Test Thoroughly - Run the application and verify all functionality works as expected
  4. Iterate as Needed - Use the generated code as a starting point and customize further by prompting the changes

Next Steps​

  • Try generating stations for an entity in your project
  • Explore the generated code to understand Mosaic patterns
  • Experiment with different AI agents and models to find what works best for your workflow