English | 한국어

Mimir-Skills

Skill-first workflow guidance, playbooks, and validators for AI coding agents working from local files.

Mimir-Skills now operates on a skill-first baseline for local-file AI coding agents. The core idea is simple: put workflow judgment rules, safety constraints, and output patterns into SKILL.md and companion references so agents can read them directly, while keeping only deterministic validation and thin local collection helpers in Python.

Current npm and npx release baseline: v0.1.3 / package version 0.1.3.

Why Mimir-Skills?

AI coding agents can already edit code, run tests, inspect CI, and prepare pull requests. What teams still lose is the context and governance around that work:

If you already use Claude Code, Codex, or another harness-driven agent workflow, Mimir-Skills is not a replacement for that harness. It adds a missing layer around the work: reusable handoff patterns, reviewer-facing rationale, and bounded CI investigation summaries that preserve intent, evidence, and next-step context.

Harnesses help agents execute more. Mimir-Skills helps teams understand, review, and continue that work safely.

• why a path was chosen
• what actually changed
• what evidence supported the choice
• whether AI-assisted tooling shaped the change and how that guidance was verified
• what approval or rollout boundary applied when blast radius mattered
• what remains risky or uncertain
• what happened after the change reached a shared workflow or operational surface
• what the next agent or reviewer should know before continuing

Mimir-Skills helps preserve that context with reusable workflow skills such as:

• prepare-handoff
• write-pr-rationale
• capture-ci-investigation

Best fit for:

• small software teams, roughly 2 to 8 engineers
• GitHub pull-request-based workflows
• developers already using local-file AI coding agents in regular engineering work

Quality boundary:

• outputs are drafts, not final truth
• human review is still required before external sharing
• CI help is best-effort and depends on the available logs and context
• automation should stay bounded, reviewable, and secondary to explicit evidence-based records
• the repository improves artifact-level traceability and governance context, but it is not yet a full deployment-control system

Getting Started

There are three practical ways to use Mimir-Skills today. See Quick Start for step-by-step commands and path details.

1. Skill-First Reading (Recommended)

Start from the workflow SKILL.md files directly:

• skills/prepare-handoff/SKILL.md
• skills/write-pr-rationale/SKILL.md
• skills/capture-ci-investigation/SKILL.md

This is the primary path for local-file agents that can open repository files directly.

2. One-Line Install

Install skills into your project with a single command. No repo clone needed:

npx mimir-skills install --target <claude|codex|generic>

Use claude, codex, or generic for the target.

Or from the repository:

python -m mimir_skills install --target <claude|codex|generic>

The installer auto-detects the target when .claude/ or .codex/ exists in the project directory. Use --target to be explicit.

After install, you can usually just tell your agent one of these:

Prepare a handoff from my current changes.
Write PR rationale for this branch.
Summarize this CI failure as a bounded investigation note.

If routing is weak or inconsistent, use the explicit fallback form:

Use the prepare-handoff workflow. Prepare a handoff from my current changes.
Use the write-pr-rationale workflow. Write PR rationale for this branch.
Use the capture-ci-investigation workflow. Summarize this CI failure as a bounded investigation note.

See Local Install for full options and details. See Prompt Macros for the portable copy-paste prompt pack.

3. Local Helpers

Use repository-root helpers when you want discovery or structured context collection before drafting from the skill.

• python -m mimir_skills list
• python skills/prepare-handoff/scripts/collect_git_context.py --repo . --output handoff-context.json
• python skills/write-pr-rationale/scripts/collect_pr_context.py --repo . --output pr-context.json

The old prepare-handoff and write-pr-rationale generate commands now exist as compatibility or deprecation stubs rather than the primary workflow path.

Optional: Obsidian Workspace

If you already use Obsidian, you can treat the linked Markdown artifacts under .ai/records/reports/ as a local review workspace. This is optional and not required for the core workflows.

• without Obsidian: keep reading JSON and Markdown directly in your editor or review flow
• with Obsidian: use backlinks and graph view to follow relationships among decision, report, and memory notes more easily

By default, Obsidian-friendly notes render under .ai/records/reports/. If you want to browse them in Obsidian, open that folder as a vault. If you later prefer a different output location, you can change it explicitly.

See Obsidian Workspace for the simple setup, expected benefits, and boundaries.

Example Requests

You can ask your agent directly with short requests like these:

• Prepare a handoff from my current changes.
• Write PR rationale for this branch.
• Summarize this CI failure as a bounded investigation note.
• Validate this decision record: .ai/records/decisions/<id>.json
• Render this decision record as an Obsidian-friendly note under the default project output location.
• Change the default Obsidian output location for this project to my vault path.

For more copy-paste prompts, including collector-assisted and Obsidian-specific variants, see Prompt Macros.

Documentation

Start here:

• Project One-Pager
• Quick Start
• Prompt Macros
• Obsidian Workspace
• Workflow Trigger Table
• Workflow Surface
• Agent Support Levels

Reference:

• Always-Loaded Rules
• Local Install
• Adapter Feedback Loop
• Skills Directory Notes
• Examples Directory Notes
• Evaluations Directory Notes
• Trigger Taxonomy v0.1
• Decision Record Schema v0.1
• Memory Promotion Policy v0.1
• Security Policy
• Contributing Guide

Repository Layout

Mimir-Skills/
  package.json
  bin/
  README.md
  README.ko.md
  docs/
  skills/
  spec/
  examples/
  evaluations/
  scripts/
  template/
  mimir_skills/

Primary public surface:

• skills/
• docs/
• spec/
• examples/

Secondary helper surface:

• scripts/
• mimir_skills/

The intended runtime artifact layout inside a user repository is:

.ai/
  records/
    decisions/
    memories/
      candidates/
      validated/
    plans/
    reports/

Current Status

The repository now runs on a skill-first baseline.

• prepare-handoff and write-pr-rationale are skill-first workflows with live collectors and deprecated generate stubs
• capture-ci-investigation is a skill-first workflow, wrapper-only by design
• canonical decision records can optionally capture AI-assistance provenance, approval state, and change-governance context for risky shared-surface changes
• workflow routing stays on the public trigger table until scale or ambiguity justifies anything machine-readable
• deterministic validators and example verification remain stable and should not grow back into a larger workflow runtime
• new agent-specific adapters stay deferred unless repeated usage shows a clear UX gain beyond the current baseline

Language Policy

• README.md is the default GitHub entry point.
• English files are the source of truth for meaning.
• Korean files are maintained only for the root README and a small entry or overview subset under docs/, currently project-one-pager, quick-start, and glossary.
• Detailed workflow docs, helper docs, skills, references, evaluations, contributor workflow files, and local planning notes stay English-first.
• Public technical specs, skills, examples, evaluations, and contributor workflow files stay English-only.
• JSON keys, schema names, and file paths stay in English across both languages.

License

Apache 2.0. See LICENSE.