Mercury Kit

AI Agent templates with Skills, Agents, and Workflows

Quick Install

npx mercury-kit init

Or install globally:

npm install -g mercury-kit
mercury-kit init

Short alias after global install:

mkit init

This installs the .agent folder containing all templates into your project.

It also creates managed bridge files so AI tools in the same workspace can automatically route through the current project's Mercury Kit setup:

• AGENTS.md for Codex-style project instructions
• .cursor/rules/*.mdc for Cursor project rules

Do not only copy the .agent/ folder by itself. If you want the assistant to prioritize local skills/workflows on future turns, you must also keep the bridge files (AGENTS.md and .cursor/rules/*.mdc) in the workspace root.

Important Note on .gitignore

If you are using AI-powered editors like Cursor or Windsurf, adding the .agent/ folder to your .gitignore may prevent the IDE from indexing the workflows. This results in slash commands (like /plan, /debug) not appearing in the chat suggestion dropdown.

Recommended Solution: To keep the .agent/ folder local (not tracked by Git) while maintaining AI functionality:

1. Ensure .agent/ is NOT in your project's .gitignore.
2. Instead, add it to your local exclude file: .git/info/exclude

What's Included

| Component | Count | Description | | ------------- | ----- | ------------------------------------------------------------------ | | Agents | 13 | Active specialist AI personas for personal development | | Skills | 43 | Domain-specific knowledge modules | | Workflows | 14 | Active slash command procedures | | Modern ES | 2026+ | Next.js 16 & React 19 Native (Cache Components, PPR, Proxy) |

Usage

Using Agents

No need to mention agents explicitly! The system automatically detects and applies the right specialist(s):

You: "Add JWT authentication"
AI: Applying @security-auditor + @backend-specialist...

You: "Fix the dark mode button"
AI: Using @frontend-specialist...

You: "Login returns 500 error"
AI: Using @debugger for systematic analysis...

How it works:

• Analyzes your request silently

• Detects domain(s) automatically (frontend, backend, security, etc.)

• Selects the best specialist(s)

• Informs you which expertise is being applied

• You get specialist-level responses without needing to know the system architecture

Benefits:

• Zero learning curve - just describe what you need
• Always get expert responses
• Transparent - shows which agent is being used
• Can still override by mentioning agent explicitly

Using Workflows

Invoke workflows with slash commands:

| Command | Description | | ---------------- | ------------------------------------- | | /new-vue-page | Create a Vue 3 + Vite route page | | /new-spring-api| Create a Spring Boot backend API | | /db-change | Plan and implement a database change | | /new-feature | Add a feature to an existing project | | /bugfix | Reproduce, diagnose, and fix a bug | | /debug | Systematic debugging | | /deploy | Deploy application | | /enhance | Improve existing code | | /plan | Create task breakdown | | /preview | Preview changes locally | | /refactor | Improve existing code safely | | /review | Review code before merge or release | | /status | Check project status | | /test | Generate and run tests |

Example:

/new-vue-page create user list page
/new-spring-api add user list endpoint
/db-change add user status column
/new-feature add profile editing
/bugfix login returns 500
/refactor simplify auth module
/review inspect recent backend changes
/debug why login fails

Using Skills

Skills are loaded automatically based on task context. The AI reads skill descriptions and applies relevant knowledge.

CLI Tool

| Command | Description | | --------------- | ----------------------------------------- | | mercury-kit init | Install .agent folder into your project | | mercury-kit update | Refresh an existing .agent installation | | mercury-kit status | Check installation status | | mkit init | Short alias for mercury-kit init |

Options

mercury-kit init --force        # Overwrite existing .agent folder
mercury-kit init --path ./myapp # Install in specific directory
mercury-kit init --dry-run      # Preview actions without executing
mercury-kit init --quiet        # Reduce output
mercury-kit update              # Refresh an existing .agent installation
mercury-kit status              # Check whether .agent is installed
mkit init                       # Short alias

Documentation

• GitHub Repository - Source code and project files
• Issues - Report bugs or track tasks

Repository

• GitHub: https://github.com/xhy1040050653/mercury-kit
• Profile: https://github.com/xhy1040050653

License

MIT