miku-grep-skills

miku-grep-skills is an Agent Skills package for using miku-grep from agent workflows.

miku-grep is a local-first grep-like runtime for AI agents and automation. It accepts short miku-grep QUERY [ROOT] arguments and returns readable text by default. Use --format json or stdin request JSON when a structured result is needed.

Access Scope

miku-grep is a local filesystem search tool, comparable in access scope to rg, grep, or find when run by the same agent process. It does not create an additional sandbox boundary. It can search any path that the host environment and filesystem permissions allow the agent process to read.

The skill workflow asks for user confirmation before searching outside the current repository or declared workspace. This is a consent gate for normal agent use, not an OS-level access restriction.

This confirmation is currently handled by the agent workflow as an in-conversation consent gate. It is not the same as a host UI permission prompt such as a VS Code Allow button, and it is not enforced by the filesystem sandbox unless the host environment separately restricts the command.

Because this gate is prompt-driven, it can fail to trigger if the agent does not follow the skill workflow or if another execution path invokes the runtime directly. Do not rely on it as a hard enforcement mechanism.

Quick Start

1. Put runtime artifacts under skills/igapyon-miku-grep/runtime/.
2. Run npm test.
3. Run npm run build:bundle.
4. Install the generated bundle/miku-grep-skills/skills/igapyon-miku-grep directory into your skill home.
5. In conversation, explicitly start with igapyon-miku-grep or miku-grep.

Typical requests:

• search file contents with a literal query
• list matching files with --files
• search file paths with a regex query
• return next-read candidates with --agent
• return structured JSON with --format json
• return detailed matches for focused inspection

Notes

• This repository does not provide MCP server integration.
• The skill is opt-in and should not activate for generic search or code investigation requests.
• The skill uses bundled CLI runtime artifacts before broad workspace exploration.
• Java and Node.js runtime artifact file versions should be selected by file name.
• With current runtime artifacts, excludeFileNamePatterns and excludeDirNamePatterns replace the corresponding default exclude presets when specified. If they are omitted, default excludes are used.
• A repository may define .mikusoft/miku-grep.json for repo-local defaults such as search limits, include patterns, encoding, and ignore behavior. Request JSON always takes precedence.

Java-Only Environments

The files under skills/igapyon-miku-grep/lib/*.mjs are Node.js helper scripts for agent environments that can run Node.js. They are not required to use the Java runtime directly.

When only Java is available, call the bundled jar directly. Prefer args-first commands for quick exploration:

java -jar skills/igapyon-miku-grep/runtime/miku-grep-<version>.jar TODO .
java -jar skills/igapyon-miku-grep/runtime/miku-grep-<version>.jar TODO . --agent
java -jar skills/igapyon-miku-grep/runtime/miku-grep-<version>.jar TODO . --format json

For complex or handoff-friendly searches, request JSON on stdin still writes result JSON to stdout:

java -jar skills/igapyon-miku-grep/runtime/miku-grep-<version>.jar < request.json > result.json

In that mode, SKILL.md and references/ provide the operating instructions, and the Java jar performs request validation, filesystem traversal, matching, exclude handling, and diagnostics. Node.js-only conveniences such as helper-based runtime selection, result formatting, and bundle tests are unavailable.

If a repo-local .mikusoft/miku-grep.json exists, copy applicable search, output, encoding, and ignore defaults into request.json manually according to the documented precedence.

Expected runtime artifact names:

• skills/igapyon-miku-grep/runtime/miku-grep-<version>.jar
• skills/igapyon-miku-grep/runtime/miku-grep-<version>.mjs

Developer Documents

• docs/quickstart.md
• docs/development.md
• docs/miku-grep-skills-config.md
• docs/skill-installation.md
• skills/igapyon-miku-grep/references/INDEX.md

License

Apache License 2.0. See LICENSE.