Skip to content

Contributing to Mirai Shared Skills

mirai-shared-skills is the centralized catalog of BaseSkill capabilities for mirai-agent-core. This guide covers how to set up the dev environment, add a new skill, author an ADR, and ship docs.

Dev environment

The project uses uv for everything — dependency management, scripts, and packaging. Install uv from https://docs.astral.sh/uv/getting-started/installation/ and then:

# Sync dev environment with all extras (Neo4j, Azure, Cohere, eval).
# This pulls mirai-agent-core from a private GitHub org — make sure your token works.
uv sync --all-extras

# Run the test suite (unit only)
uv run pytest tests/

# Run integration tests (requires Docker for Neo4j)
docker compose -f docker-compose.test.yml up -d
uv run pytest tests/ -m integration

# Type-check
uv run mypy mirai_shared_skills tests

# Lint + format
uv run ruff check . && uv run ruff format --check .

# Serve docs locally
uv run mkdocs serve   # opens http://127.0.0.1:8000

# Build docs (also runs in CI as `mkdocs build --strict`)
uv run mkdocs build --strict

Adding a new skill

  1. Decide whether your skill is standard (safe-by-default) or raw (must-be-wrapped). See ADR-0001. If it's raw, the docs must explicitly state the wrapping requirement.
  2. Create a subpackage under mirai_shared_skills/<your_skill>/ (or a single file at mirai_shared_skills/<your_skill>.py for tiny skills).
  3. Implement a BaseSkill subclass with instructions: str and a get_tools() method that returns Tool objects via tool_from_function (see ADR-0007).
  4. If your skill ships long-form guidance, drop it under <your_skill>/references/*.md and reference those paths in the descriptor (see ADR-0008).
  5. Register a SkillDescriptor in mirai_shared_skills/__init__.py's bootstrap([...]) call.
  6. Add a docs page at docs/skills/<your-skill>.md following the standard template (intro / when-to-use / tools / configuration / example / security / related). Mirror the existing skill pages.
  7. Wire the new page into mkdocs.yml under Foundational Skills or Domain Skills.
  8. Add unit tests under tests/<your_skill>/. Use respx for HTTP mocks. See the Testing guide.

Authoring an ADR

ADRs are immutable records of architectural decisions. Use the existing ADRs as templates — ADR-0001 is canonical.

  1. Pick the next number: count the existing files in docs/adrs/ (currently up to 008).
  2. Create docs/adrs/adr-NNN-slugified-title.md. The filename must be lowercase, hyphen-separated.
  3. Use the Nygard-style template: Date, Authors, Status, Approval State, Implementation State, then sections (1) Context, (2) Decision Drivers, (3) Considered Options, (4) Decision Outcome with 4.1 Validation, (5) Pros and Cons, (6) Consequences, (7) Implementation Plan, (8) References.
  4. Add the ADR to the nav in mkdocs.yml (under Architecture > ADRs).
  5. Add a row to docs/architecture/adrs.md and docs/architecture/ARCHITECTURE.md.
  6. Once approved, set Status: Accepted and Implementation State: Completed (or In Progress).

ADRs are immutable once accepted. If a later decision changes course, write a new ADR that supersedes the old one (don't edit the old one).

Branch + PR conventions

  • Branch from main. Branch names: feat/<short-desc>, fix/<short-desc>, docs/<short-desc>, chore/<short-desc>.
  • PR titles use the same prefixes: feat: add Salesforce skill.
  • Each PR must pass: ruff check, mypy --strict, pytest tests/, and mkdocs build --strict. CI enforces all four.
  • If your PR adds a skill, the same PR must include the docs page.
  • If your PR makes an architectural decision, the same PR must include the ADR.

Docs deployment

The docs site is published at https://mirai-shared-skills.pages.dev via Cloudflare Pages. The deployment is fully automated — .github/workflows/docs.yml builds and deploys on every push to main that touches docs/, mirai_shared_skills/, mkdocs.yml, pyproject.toml, uv.lock, or CONTRIBUTING.md.

One-time setup (only done by repo admins):

  1. Create a Cloudflare Pages project named mirai-shared-skills in Direct Upload mode (no Git integration; the workflow uploads).
  2. Add two repository secrets in GitHub: CLOUDFLARE_API_TOKEN (with the Cloudflare Pages: Edit permission) and CLOUDFLARE_ACCOUNT_ID. The agent-core repo already has these — reuse the same values.
  3. The existing MIRAI_CI_APP_ID / MIRAI_CI_APP_PRIVATE_KEY secrets used by ci.yml are also needed by docs.yml (they mint the short-lived token to clone mirai-agent-core from the private org during uv sync).

To check deployment status, click the Deployments tab in the GitHub UI — the workflow surfaces the Cloudflare deploy URL on every commit.