Overview

Use this skill to deliver production-ready changes for @v-miniapp/ai and @v-miniapp/cli workflows.

Process

🚀 High-Level Workflow

Phase 1: Deep Research and Planning

1.1 Understand Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.

Context Management: Agents benefit from concise tool descriptions and the ability to filter/paginate results. Design tools that return focused, relevant data. For list/search/retrieval tools, prefer one flexible tool with many optional filters instead of several narrow variants so users can ask in different ways without changing the tool shape. Some clients support code execution which can help agents filter and process data efficiently.

Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions and next steps.

1.2 Study MCP Protocol Documentation

Navigate the MCP specification:

Start with the sitemap to find relevant pages: https://modelcontextprotocol.io/sitemap.xml

Then fetch specific pages with .md suffix for markdown format (e.g., https://modelcontextprotocol.io/specification/draft.md).

Key pages to review:

• Specification overview and architecture
• Transport mechanisms (streamable HTTP, stdio)
• Tool, resource, and prompt definitions

1.3 Study Framework Documentation

Core defaults

• Prefer pnpm unless the user explicitly requests npm or yarn.
• Assume Node.js >=22.
• Prefer official entry points:
  • @v-miniapp/ai/server
  • @v-miniapp/ai/web
  • @v-miniapp/ai/apis

Reference framework documentation:

• references/cli.md for project bootstrap and v-cli usage.
• references/server.md for MCP tools/resources/prompts/skills and server contracts.
• references/skill.md for bundled skill authoring, frontmatter, and registerSkill(...) naming/registration rules.
• references/web.md for React widget hooks and rendering lifecycle.
• references/apis.md for imperative/non-React bridge calls.

1.4 Study Project Structure

See Project structure - Project structure, package.json, app-config.json

1.5 Plan Your Implementation

Understand the API: Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.

Tool Selection: Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.

Phase 2: Init project and Structure

Skip this phase if the project already exists.

2.1 Init project

• Follow CLI reference for bootstrap commands and v-cli usage.
• Prefer creating AI apps with the ai-app-blank template (v-cli create <project-name> --ai-app --ai-template ai-app-blank).
• Before creating a new app, verify whether the current workspace is already initialized.
• If the project is already initialized, do not create/scaffold a new project again.
• After scaffold/init, remove generated tools, skills, and web parts that are not needed for the current task.

2.2 Set Up Project Structure

When creating app-config.json, ask the user to provide:

• name
• appId
• description

Set version to 1.0.0 by default if the user does not specify one.

Phase 3: Implementation

Note: You should create multiple skills and multiple widgets as needed to fit the application's requirements. Each skill encapsulates an independent group of functionality; each widget is a separate UI component bound to a specific tool.

Example: For a task management app, tasks_list (showing all tasks) and task_detail (showing a single task) should be two separate widgets — not combined into one. Each widget maps to its own tool (list_tasks → TasksListWidget, get_task → TaskDetailWidget), keeping concerns isolated and rendering predictable.

3.1 Implement server

• Follow Server reference for contracts and API surface (McpServer, registration methods, createStructuredResult).
• Follow Skill reference when the app needs packaged skills under skills/<skill-name>/SKILL.md.
• Define tool/resource/prompt/skill names explicitly and keep inputSchema deterministic.
• Keep business logic in server handlers; return stable structuredContent and human-readable content.
• Use createStructuredResult(structuredContent, text?) to keep server-widget output shape consistent.
• Register widget resources intentionally and wire resourceName for tools that render UI.
• Use McpTool, McpResource, McpPrompt, and McpSkill wrappers when reusable typed configs improve maintainability.
• For list/search tools, prefer broad optional filters in inputSchema so one tool can support multiple user intents, for example limit, offset, search, sortBy, status, category, and numeric ranges such as pricingMin/pricingMax.
• Validate runtime setup: env loading, server info fallback, and port resolution (options.port -> PORT -> 4000).
• Ensure registerSkill('<skill-name>') matches the folder name in skills/<skill-name>/SKILL.md.
• Keep skill guidance inside the packaged skills/<skill-name>/SKILL.md file, with valid YAML frontmatter (name, description) and optional metadata.binding-tools only when the bound tools are actually registered.

3.2 Implement web

• Follow Web reference for React widget lifecycle and hook-based integration patterns.
• Use useToolInfo<'tool-name'>() with getStructuredResult(...) for passive initial hydration from host/tool result.
• Use one useCallTool('tool-name') per user action and handle idle | pending | success | error states explicitly.
• Build host-aware UI with useHostContext(), useLayout(), useDisplayMode(), and useUser().
• Persist lightweight widget-local state with useWidgetState(defaultState?) instead of ad-hoc globals.
• Trigger AI follow-up turns with useSendFollowUpMessage() when user flow needs another model interaction.
• When navigating between screens/views that require a new AI turn, use apis.sendFollowUpMessage(message) (imperative) or useSendFollowUpMessage() (React hook) to programmatically trigger a new message and drive the next model interaction. Simple screens such as popups, status displays, or lightweight views may not need this.
• Mount widget entry once via renderWidget(<App />) and keep contracts aligned with server structuredContent.
• For non-React/imperative integration, follow APIs reference instead of web hooks.

Phase 4: Review and Test

4.1 Code Quality

Review for:

• No duplicated code (DRY principle)
• Consistent error handling
• Clear tool descriptions
• Lint passes with no errors or warnings
• No unused variables or imports remain

4.2 Build and Test

• Run pnpm/npm/yarn run dev to verify compilation
• The app will start both the server and inspector on two separate ports.
  • If you encounter an error indicating a port conflict, please kill the process using that port.
  • Read the std output in the terminal to check if the app throw any errors.

Reference Files

📚 Documentation Library

Load these resources as needed during development:

Core MCP Documentation (Load First)

• MCP Protocol: Start with sitemap at https://modelcontextprotocol.io/sitemap.xml, then fetch specific pages with .md suffix
• MCP Best Practices - Universal MCP guidelines including:
  • Server and tool naming conventions
  • Response format guidelines (JSON vs Markdown)
  • Pagination best practices
  • Transport selection (streamable HTTP vs stdio)
  • Security and error handling standards

SDK Documentation

• CLI reference - bootstrap commands and v-cli workflows.
  • Setup new project
  • Start
  • Build
• Server reference - MCP server contracts, tools/resources/prompts/skills.
• Skill reference - bundled SKILL.md format, registration, and authoring checklist.
• Web reference - React widget hooks and tool lifecycle patterns.
• APIs reference - low-level imperative bridge integration.