How do I install the Moss Pikachu skill?

Run npx skillmds@latest add usemoss/moss-pikachu in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Moss Pikachu safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Moss Pikachu?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Moss Pikachu free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Moss Pikachu?

usemoss (@usemoss) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Moss Pikachu by usemoss — Agent Skill

Name: Moss Pikachu
Author: usemoss

Moss Pikachu

Build and maintain Moss Pikachu, a macOS menu bar semantic file search app using Moss Python SDK (PyPI moss>=1.6.0), FSEvents, SwiftUI, and Pikachu pet animations. Use when working on MossPikachu, moss_worker.py, FileMonitor, SearchService, menu bar overlay, or Moss integration in this repository.

usemoss b4aa404 8 files · 9.6 KB Updated Sep 17, 2026

File contents

Moss Pikachu Agent Skill

Project docs (start here)

Doc	Purpose
project-summary.md	Full technical reference
how-to.md	End-user guide
contribution.md	Contributor guide

Specialized skills

Skill	Use when
moss-pikachu-semantic-search	Search quality, query tuning
moss-pikachu-indexing	Indexing, manual/automatic modes
moss-pikachu-contributing	PRs and contribution workflow

Read order

architecture.md
moss-integration.md
macos-patterns.md
ui-animations.md
pitfalls.md

Non-negotiables

Xcode .app bundle — not a root-level SPM executable for the menu bar app
macOS-only target — SUPPORTED_PLATFORMS = macosx
Python worker for Moss on macOS — Moss Swift SPM is iOS-only
pip install moss>=1.6.0 — GitHub main sdks/python/sdk lacks SessionIndex API
No hardcoded credentials — MOSS_PROJECT_ID / MOSS_PROJECT_KEY via Keychain or env
NSPanel for search overlay — not WindowGroup (avoids Dock icon)

Phase gates

Run before advancing phases:

./.cursor/skills/moss-pikachu/scripts/validate-phase.sh 1
./.cursor/skills/moss-pikachu/scripts/validate-phase.sh 2
./.cursor/skills/moss-pikachu/scripts/validate-phase.sh 3

Task sequencing

Phase	Scope
1	Menu bar, hotkey, search overlay shell, settings window
2	FileMonitor, moss_worker.py, MossBridge, SearchService
3	Pikachu animations, live search UI, settings, polish

Do not wire live search before MossBridge + SearchService compile and pass Phase 2 validation.

Code conventions

@MainActor for all UI updates
async/await for MossBridge calls (not callbacks)
Line-delimited JSON between Swift and Python (\n terminated)
Debounce FSEvents (100ms) and search input (200ms)
MARK: sections in Swift service files

---name: moss-pikachudescription: Build and maintain Moss Pikachu, a macOS menu bar semantic file search app using Moss Python SDK (PyPI moss>=1.6.0), FSEvents, SwiftUI, and Pikachu pet animations. Use when working on MossPikachu, moss_worker.py, FileMonitor, SearchService, menu bar overlay, or Moss integration in this repository.---# Moss Pikachu Agent Skill## Project docs (start here)| Doc | Purpose ||-----|---------|| [project-summary.md](../../project-summary.md) | Full technical reference || [how-to.md](../../how-to.md) | End-user guide || [contribution.md](../../contribution.md) | Contributor guide |## Specialized skills| Skill | Use when ||-------|----------|| [moss-pikachu-semantic-search](../moss-pikachu-semantic-search/SKILL.md) | Search quality, query tuning || [moss-pikachu-indexing](../moss-pikachu-indexing/SKILL.md) | Indexing, manual/automatic modes || [moss-pikachu-contributing](../moss-pikachu-contributing/SKILL.md) | PRs and contribution workflow |## Read order1. [architecture.md](architecture.md)2. [moss-integration.md](moss-integration.md)3. [macos-patterns.md](macos-patterns.md)4. [ui-animations.md](ui-animations.md)5. [pitfalls.md](pitfalls.md)## Non-negotiables- **Xcode `.app` bundle** — not a root-level SPM executable for the menu bar app- **macOS-only target** — `SUPPORTED_PLATFORMS = macosx`- **Python worker** for Moss on macOS — Moss Swift SPM is iOS-only- **`pip install moss>=1.6.0`** — GitHub `main` `sdks/python/sdk` lacks `SessionIndex` API- **No hardcoded credentials** — `MOSS_PROJECT_ID` / `MOSS_PROJECT_KEY` via Keychain or env- **NSPanel** for search overlay — not `WindowGroup` (avoids Dock icon)## Phase gatesRun before advancing phases:```bash./.cursor/skills/moss-pikachu/scripts/validate-phase.sh 1./.cursor/skills/moss-pikachu/scripts/validate-phase.sh 2./.cursor/skills/moss-pikachu/scripts/validate-phase.sh 3```## Task sequencing| Phase | Scope ||-------|-------|| 1 | Menu bar, hotkey, search overlay shell, settings window || 2 | FileMonitor, moss_worker.py, MossBridge, SearchService || 3 | Pikachu animations, live search UI, settings, polish |Do not wire live search before MossBridge + SearchService compile and pass Phase 2 validation.## Code conventions- `@MainActor` for all UI updates- `async/await` for MossBridge calls (not callbacks)- Line-delimited JSON between Swift and Python (`\n` terminated)- Debounce FSEvents (100ms) and search input (200ms)- `MARK:` sections in Swift service files

Frequently asked questions