Skip to content
Back to home

Grimoire

Open source catalog of reusable skills and workflows for AI agents, installable in Claude Code and Codex.

Repository

Problem

AI agent skills and workflows are usually tied to a single tool and copied by hand from one tool to another.

Decisions

  • Platform-agnostic architecture: one canonical implementation per skill and documented packaging per tool.
  • Repository contracts verified by Python tests and behavior evaluations with recorded scenarios and results.
  • Implementation, documentation, tests and platform integration kept separate.

Stack

  • Python
  • Markdown
  • Claude Code
  • Codex

Result

Open source catalog with 15 skills, one of them orchestrating a composed workflow (chain), packaged for Claude Code, Codex, Pi and Hermes Agent, with a suite of 41 Python tests.

Learnings

Defining stable contracts across different tools and testing agent behavior, not only code.

How I used AI

The product is instructions for AI agents, so skill changes are evaluated with agents: each scenario has observable criteria, runs against the current skills to record the RED result, and runs again after the smallest fix to record the GREEN result, in a fresh context and an isolated sandbox. No scenario is marked as passing from reading SKILL.md alone. The repository's structural contracts are checked by Python tests.

Evidence

  • Source code and installation guides on GitHub
  • $ python -m unittest discover -s tests
...
Ran 41 tests in 0.035s

OK
    Suite with 41 Python tests (tests/test_repository.py): all pass in a local run at commit d15acbb
  • ILUSTRAÇÃO · ILLUSTRATION skills/<nome>/SKILL.md (15) chains/business-direction.md manifesto · manifest: entrypoint + 8 skills business-direction entrypoint business-research product-scope market-positioning sales-pipeline financial-planning operations-planning strategy-synthesis skills avulsas · standalone skills (7) fora da chain · outside the chain route-context evolve-skills model-routing-policy project-design web-design-psychology github-issues gamification-psychology Fonte · Source: README.md, chains/business-direction.md, skills/
    IllustrationCatalog structure: 15 skills under skills/, 8 composed by the business-direction chain manifest and 7 standalone
  • ILUSTRAÇÃO · ILLUSTRATION README.md skills/ <name>/SKILL.md Claude Code .claude-plugin/plugin.json marketplace.json: grimoire@migliatti Codex .codex-plugin/plugin.json skills: ./skills/ Pi .pi/settings.json skills: ../skills + extensions/ Hermes Agent docs/installation/hermes-agent.md external_dirs · GitHub tap ──▶ exposta a · exposed to skills/ = implementação canônica · canonical implementation Fonte · Source: README.md, docs/installation/
    IllustrationPer-platform packaging: the same canonical implementation under skills/ is exposed to Claude Code, Codex, Pi and Hermes Agent
  •     def test_packaged_version_is_consistent(self) -> None:
        claude = self.load(".claude-plugin/plugin.json")
        codex = self.load(".codex-plugin/plugin.json")
        marketplace = self.load(".claude-plugin/marketplace.json")
        entry = next(
            item for item in marketplace["plugins"] if item["name"] == PLUGIN_NAME
        )
        self.assertEqual(claude["version"], codex["version"])
        self.assertEqual(claude["version"], entry["version"])

    Test that enforces the same version across the Claude Code, Codex and marketplace manifests (tests/test_repository.py) View in repository

  •     def test_canonical_skills_are_vendor_neutral(self) -> None:
        banned = ("~/.claude", ".codex/skills", "AskUserQuestion")
        for path in (ROOT / "skills").glob("*/SKILL.md"):
            text = path.read_text(encoding="utf-8")
            for token in banned:
                self.assertNotIn(token, text, f"{token} in {path}")

    Test that keeps platform-specific references out of the canonical skills (tests/test_repository.py) View in repository