forge-plugin/skills/generate-mock-service/
├── SKILL.md                  # This file - mandatory workflow
├── examples.md               # Usage scenarios and examples
├── scripts/
│   └── mock_generator.py     # Helper script for mock generation
└── templates/
    ├── express_mock_template.js        # Express.js mock server template
    ├── flask_mock_template.py          # Flask mock server template
    ├── fastapi_mock_template.py        # FastAPI mock server template
    ├── wiremock_template.json          # WireMock mapping template
    ├── prism_config_template.yml       # Prism mock server template
    └── dockerfile_mock_template.txt    # Dockerfile for mock services

Required Reading

Before executing this skill, load context and memory via interfaces:

Context: Use contextProvider.getDomainIndex() for relevant domain context. See ContextProvider Interface.
Skill memory: Use memoryStore.getSkillMemory("generate-mock-service", "{project-name}") for previous mock configurations. See MemoryStore Interface.

Interface References

Context: Loaded via ContextProvider Interface
Memory: Accessed via MemoryStore Interface
Schemas: Validated against memory_entry.schema.json

Design Requirements

Core Functionality

This skill must:

Understand the external service to mock (API contract, endpoints, responses)
Ask user about mock requirements (service type, endpoints, response patterns)
Choose appropriate mocking strategy (code-based, WireMock, Prism, etc.)
Generate mock service implementation (server code or configuration)
Create realistic response data (sample JSON, XML, or other formats)
Support different scenarios (success, error, edge cases)
Provide containerization (Dockerfile, docker-compose integration)
Store mock configuration in memory for future reference

Output Requirements

Generate a complete, working mock service with:

Mock server implementation (Express, Flask, FastAPI, WireMock, or Prism)
Endpoint definitions matching the real service API
Realistic sample responses for all endpoints
Support for different HTTP methods (GET, POST, PUT, DELETE, PATCH)
Configurable delays to simulate network latency
Error scenario support (4xx, 5xx responses)
Request validation (optional)
Dockerfile for containerization
docker-compose configuration for integration
README with usage instructions

Quality Requirements

Generated mocks must:

Match the real API contract (OpenAPI/Swagger spec if available)
Provide realistic responses (proper data types, structures)
Support multiple scenarios (success, validation errors, server errors)
Be easily configurable (environment variables, config files)
Include logging (request/response logging for debugging)
Be containerized (ready to run in Docker)
Be well-documented (clear setup and usage instructions)

Prompting Guidelines

User Questions Framework

After understanding the mock requirements, ask user about:

1. Service to Mock

Question: "What service do you need to mock?"
- External REST API
- SOAP service
- GraphQL API
- gRPC service
- WebSocket service
- Third-party integration (Stripe, SendGrid, etc.)
Why ask: Determines mock server type and configuration
Follow-up: "Do you have an API specification (OpenAPI, Swagger, WSDL)?"

2. Mock Implementation Type

Question: "What type of mock implementation do you prefer?"
- Code-based: Express.js (Node.js), Flask (Python), FastAPI (Python)
- Configuration-based: WireMock (JSON), Prism (OpenAPI), MockServer
- Simple: JSON Server (for REST APIs)
Why ask: Determines which templates to use
Recommendation:
- Use Prism if you have OpenAPI spec
- Use WireMock for complex scenarios
- Use code-based for custom logic

3. Endpoints and Methods

Question: "What endpoints need to be mocked?"
- List all endpoints (e.g., /users, /orders, /payments)
- HTTP methods for each (GET, POST, PUT, DELETE, PATCH)
- Request/response formats (JSON, XML, form data)
Why ask: Determines mock routes and handlers
Follow-up: "Do you have example request/response payloads?"

4. Response Scenarios

Question: "What response scenarios do you need?"
- Success responses (200, 201, 204)
- Client errors (400, 401, 403, 404, 422)
- Server errors (500, 502, 503)
- Edge cases (timeouts, rate limits)
Why ask: Determines scenario configuration
Follow-up: "Should scenarios be triggered by specific request parameters?"

5. Data Requirements

Question: "What kind of data should the mock return?"
- Static data (same response every time)
- Dynamic data (randomized, time-based)
- Stateful (track state across requests)
- Realistic fake data (using Faker library)
Why ask: Determines data generation approach

6. Behavior Configuration

Question: "What behavior should the mock have?"
- Response delays (simulate network latency)
- Random failures (simulate unreliable service)
- Request validation (validate required fields)
- State management (CRUD operations)
- Callback/webhook simulation
Why ask: Determines mock server logic

7. Port and Networking

Question: "What port should the mock service run on?"
- Default ports: 8080, 8081, 3001, etc.
- Custom port
Why ask: Prevents port conflicts
Follow-up: "Should this integrate with your docker-compose setup?"

8. Authentication/Authorization

Question: "Does the service require authentication?"
- No authentication
- API key validation
- OAuth2/JWT token validation
- Basic authentication
Why ask: Determines authentication middleware

Instructions

MANDATORY STEPS (Must Execute in Order)

Step 1: Initial Analysis

Purpose: Understand the service to be mocked

Actions:

Identify the external service to mock
Check if API specification exists (OpenAPI/Swagger, Postman collection, WSDL)
Review any existing documentation or examples
Determine integration points in the codebase
Note any existing mock implementations

Output: Clear understanding of service to mock and requirements

Step 2: Load Index Files

Purpose: Understand available context and memory

Actions:

Use contextProvider.getDomainIndex() for relevant context files. See ContextProvider Interface.
Use memoryStore.getSkillMemory("generate-mock-service", "{project-name}") to check for existing memory. See MemoryStore Interface.
Identify which context domains are relevant to the mock target

Output: Knowledge of available guidance and memory structure

Step 3: Load Project Memory (if exists)

Purpose: Understand previous mock configurations for this project

Actions:

Use memoryStore.getSkillMemory("generate-mock-service", "{project-name}") to load project memory. See MemoryStore Interface.
If memory exists, review:
- mock_config.md - Previous mock configurations
- generated_mocks.md - What mocks were generated before
- scenarios.md - Documented scenarios
- integration_notes.md - Integration information
If not exists, note this is first-time generation

Output: Understanding of project mock history or recognition of new project

Step 4: Load Context

Purpose: Load relevant API mocking knowledge

Actions:

Read relevant context files based on service type:
- REST API patterns
- Testing best practices
- Mock service patterns
Note any best practices for mocking

Output: Comprehensive understanding of mocking patterns

Step 5: Gather Requirements

Purpose: Understand user's needs through conversation

Actions:

Ask user about service to mock
Ask about mock implementation type
Ask about endpoints and methods
Ask about response scenarios
Ask about data requirements
Ask about behavior configuration
Ask about port and networking
Ask about authentication/authorization
Confirm all requirements with user before proceeding

Output: Complete specification of mock service to generate

Step 6: Generate Mock Service

Purpose: Create mock service implementation

Actions:

A. For Code-Based Mocks (Express/Flask/FastAPI):

Generate main server file:
- Use appropriate template (express_mock_template.js, flask_mock_template.py, fastapi_mock_template.py)
- Add endpoint handlers for each route
- Implement request validation if needed
- Add authentication middleware if required
- Configure CORS for browser access
- Add logging middleware
Generate response data files:
- Create data/ directory
- Generate JSON files for each endpoint response
- Include multiple scenarios (success, error)
- Use realistic fake data if requested
Generate utility functions:
- Response delay simulator
- Random error generator
- Fake data generator (using Faker or similar)
- Request validator
Generate configuration file:
- config.json or .env file
- Port configuration
- Delay settings
- Error rate settings
- Feature flags

B. For Configuration-Based Mocks (WireMock/Prism):

Generate WireMock mappings (if using WireMock):
- Create mappings/ directory
- Generate JSON mapping files for each endpoint
- Include request matchers
- Define response templates
- Add scenario state transitions if needed
Generate Prism configuration (if using Prism):
- Use existing OpenAPI specification
- Create prism-config.yml
- Configure dynamic response behavior
- Set up validation rules

C. Common Files:

Generate Dockerfile:
- Use templates/dockerfile_mock_template.txt
- Install dependencies
- Copy server files and data
- Expose port
- Set startup command
Generate docker-compose integration:
- Add service definition
- Configure networking
- Set environment variables
- Add health check
- Link to other services if needed
Generate package/dependency files:
- package.json for Node.js
- requirements.txt for Python
- Include necessary libraries (express, flask, fastapi, faker, etc.)
Generate README.md:
- Service description
- Available endpoints
- Request/response examples
- How to run locally
- How to run in Docker
- Configuration options
- Testing tips
Generate test examples:
- examples/ directory
- curl commands for each endpoint
- Example request payloads
- Expected responses

Output: Complete mock service implementation

Step 7: Validate Generated Mock

Purpose: Ensure mock service is correctly configured

Actions:

Verify all required files exist
Check server code syntax
Validate JSON response files
Ensure Dockerfile is properly structured
Check that all endpoints are defined
Verify configuration is complete

Do NOT start the server - just validate file structure and syntax

Output: Confidence that generated mock is correct

Step 8: Present Results to User

Purpose: Show user what was generated and how to use it

Actions:

List all generated files with brief description
Show example endpoints and responses

Provide usage instructions:

# Run locally (Node.js example)
cd mock-{service-name}
npm install
npm start

# Run with Docker
docker build -t mock-{service-name} .
docker run -p {port}:{port} mock-{service-name}

# Or with docker-compose
docker-compose up mock-{service-name}

Show how to test endpoints:

# Example API call
curl http://localhost:{port}/api/users

Point to README.md for detailed documentation
Explain how to modify responses or add scenarios

Output: User understands how to use the mock service

Step 9: Update Project Memory

Purpose: Store configuration for future reference

Actions:

Use memoryStore.update(layer="skill-specific", skill="generate-mock-service", project="{project-name}", ...) to store:
mock_config.md:
- Service being mocked
- Mock type (Express, Flask, WireMock, etc.)
- Port configuration
- Endpoints implemented
- Authentication approach
Create generated_mocks.md:
- List of all generated files
- Timestamp of generation
- Skill version used
Create scenarios.md:
- Documented response scenarios
- How to trigger different scenarios
- Test cases covered
Create integration_notes.md:
- How mock integrates with main application
- Docker compose configuration
- Environment variables used
- Known limitations

Output: Memory stored for future skill invocations

Best Practices

Mock Design

Match the real API: Use same endpoints, methods, request/response formats
Provide realistic data: Don't just return {"success": true}
Support error scenarios: Test your error handling code
Add delays: Simulate real network conditions
Version your mocks: Track changes to mock behavior

Response Design

Use proper status codes: 200, 201, 400, 404, 500, etc.
Include all response fields: Match the real API structure
Vary responses: Support different scenarios
Add realistic timestamps: Use current dates/times
Include pagination: If the real API paginates

Configuration

Make it configurable: Use environment variables
Easy scenario switching: Change behavior without code changes
Toggle features: Enable/disable authentication, validation
Adjust timing: Configure delays, timeouts
Control data: Switch between datasets

Integration

Use same port in dev: Match production configuration
Document differences: Note what's mocked vs real
Easy switching: Toggle between mock and real service
Container-ready: Always provide Docker setup
Version control: Commit mocks to repository

Error Handling

Common Issues

Port conflicts: Check for existing services on the port
CORS errors: Configure CORS headers properly
Invalid JSON: Validate all response files
Missing dependencies: Ensure all packages are installed
Authentication failures: Mock auth tokens correctly

Debugging

Enable verbose logging: See all requests/responses
Test endpoints manually: Use curl or Postman
Check Docker logs: docker logs <container>
Validate responses: Ensure they match expected format
Compare with real API: Verify mock behavior matches

Mock Implementation Options

Express.js (Node.js)

Best for: JavaScript/TypeScript projects
Pros: Easy to customize, familiar for frontend devs
Cons: Requires Node.js installation

Flask (Python)

Best for: Python projects
Pros: Simple, minimal code
Cons: May need additional libraries for complex scenarios

FastAPI (Python)

Best for: Modern Python projects, API-first
Pros: Automatic validation, great documentation
Cons: Slightly more complex setup

WireMock

Best for: Complex scenarios, stateful mocks
Pros: Very powerful, no coding required
Cons: JSON configuration can be verbose

Prism

Best for: OpenAPI/Swagger specs available
Pros: Validates requests, generates examples automatically
Cons: Requires OpenAPI specification

JSON Server

Best for: Simple REST APIs, prototyping
Pros: Zero configuration, very fast setup
Cons: Limited customization

Version History

1.1.0 (2026-02-10): Phase 4 Migration
- Migrated to interface-based patterns (ContextProvider + MemoryStore)
- Added YAML frontmatter with declarative context/memory configuration
- Removed hardcoded filesystem paths
- Added interface references section
1.0.0 (2026-02-06): Initial implementation
- Multiple mock server types (Express, Flask, FastAPI, WireMock, Prism)
- Realistic response generation
- Multiple scenario support
- Docker containerization
- Authentication middleware
- Request validation
- Memory system for configuration tracking

Related Skills

generate-tilt-dev-environment: For integrating mocks into development environment
generate-azure-functions: May need mocks for Azure services
test-cli-tools: For testing CLI tools that call mocked services

generate-mock-service

Skill: generate-mock-service

Title

File Structure