The company-wide home for working with LLM agents consistently: reusable agent skills, thin
agents, human methodology & standards docs, and the binding templates that wire them into
any project. Runs identically on Claude Code and opencode from one set of sources — see
docs/environment/dual-cli/.
A curated, self-validating catalogue. Skills carry reusable knowledge; agents are thin
execution wrappers; docs/ is the human canon (method, engineering standards, philosophy);
prompts/ holds the agentic-file templates. The root binding is AGENTS.md-canonical:
AGENTS.md is the CLI-agnostic operating manual (read natively by opencode) and CLAUDE.md is a
thin pointer that adds only Claude-specific guidance (no symlink between them). It also carries the
spine — the durable, traceable spec backbone
(an OpenSpec instance + a forked meaningfy schema under
openspec/ and spine/) — that threads a requirement all the way to a commit.
External skills (superpowers, stream-coding, …) are referenced, not copied.
Bundles are organised by the role (hat) you wear — install meaningfy-core plus your role(s):
- Builders / developers — clean, layered, well-tested Python driven through an AI build loop.
- Architects / modellers — system design and the living conceptual (domain) model.
- Consultants — advisory work: semantic-tech coaching, decision packages, proposals, estimation.
23 skills in 4 role bundles — every skill lives in exactly one bundle (no duplication); the
table below is bundle-level only. For the per-skill picture — purpose, which cross-cutting concern
each one serves, and which skills depend on which — see
docs/skill-inventory.md (a generated map + tables, not hand-maintained).
| Bundle | Skills | Install if you… |
|---|---|---|
| meaningfy-core | technical-writing · explanatory-writing · writing-antipatterns · meaningfy-git-workflow · guardrails | …do anything (cross-cutting basics) |
| meaningfy-consulting | semantic-consulting-coach · decision-package · proposal-writing · estimation · executive-communication | …do advisory / front-of-funnel work |
| meaningfy-architecture | architecture · conceptual-modelling · modelling-conventions · linkml-engineering | …design systems or model a domain |
| meaningfy-building | epic-planning · spec-stewardship · clarity-gate · bdd-gherkin · meaningfy-code-review · cosmic-python · project-setup · ci-cd-delivery · meaningfy-release | …build software with the spine |
Thin agent wrappers live in agents/ — epic-planner, implementer,
code-reviewer — they pin a model + tools and load the skills above.
The spine is a capability, not a bundle.
meaningfy-buildingcarries the skills that drive it; the durable spine assets (openspec/+ the forked schema +spine/docs) are projected into your repo by theproject-setupskill. A spine repo reuses OpenSpec-native artifacts: an EPIC is the OpenSpecproposal.md; a PLAN isdesign.md+tasks.md.
Runs on Claude Code and opencode, from the same sources, with gate-verified parity — pick either, you don't need both.
Start here: docs/environment/setup.md. It's the canonical,
CLI-agnostic entry point — what to install and why — and links you into your CLI's literal,
copy-paste step-by-step (bundles, mandatory deps, root binding, spine commands, an MCP server if you
want one, and a verify step) from there. You shouldn't need to go looking for any other doc to get
installed.
Skill or agent? The rule of thumb.
- A skill is on-demand knowledge / method loaded into your current chat — "guide me through X". You keep the wheel.
- An agent is a delegated worker in its own fresh context with a fixed role, model, and tools — "go do X and report back". It keeps your main context clean.
- skill = teach / guide me; agent = delegate a whole task. The Meaningfy agents
(
epic-planner,implementer,code-reviewer) each just load the relevant skills and run them in isolation.
What do I reach for?
| I want to… | Reach for (in order) |
|---|---|
| Know the code rules (principles, anti-patterns, naming, exceptions, config, layering) | the code-principles catalogue — owned by cosmic-python, the single source; every skill/doc cites its PR-/BP-/AP- ids |
| Stand up a new repo | project-setup skill → scaffolds layout, tooling, tests, docs, CI, and the spine |
| Build one epic | the loop below (epic-planner → bdd-gherkin → implementer → code-reviewer) |
| Win / scope a client engagement | semantic-consulting-coach (think it through) → decision-package (produce it) → proposal-writing + estimation |
| Model a domain | conceptual-modelling (the living model + source decision) · modelling-conventions (shared craft) |
| Author LinkML / generate typed artefacts | linkml-engineering (LinkML → Pydantic/OWL/SHACL, custom templates, gates) |
| Design a system | architecture (C4, ADRs, contracts) |
| Write a board paper / client note | executive-communication |
| Write docs / a README | technical-writing |
| Write a clear explainer / blog-style explanation | explanatory-writing |
| Ship a service | ci-cd-delivery (deploy contract) |
| Cut / publish a release | meaningfy-release (versioning, release branches, PyPI, release notes) |
The build loop, step by step (one epic). Drives the OpenSpec /opsx verbs — full map in
spine/workflows.md:
| # | Step | /opsx verb |
Driven by |
|---|---|---|---|
| 1 | Gather seeds + elicit (incl. test-scenario interview) | explore |
epic-planner agent ◦ epic-planning (+ superpowers:brainstorming) |
| 2 | Shape the EPIC (= proposal.md) |
propose |
epic-planner agent ◦ epic-planning |
| 3 | Derive the PLAN (design.md + tasks.md) + author .feature scenarios (design-phase artifact) |
— | epic-planner agent ◦ epic-planning + bdd-gherkin |
| 4 | Gate the PLAN (≥9/10, incl. scenario coverage) | — | clarity-gate skill |
| 5 | Implement: step definitions + code (TDD, layered) | apply |
implementer agent ◦ cosmic-python + superpowers:test-driven-development |
| 6 | Verify / review | verify |
code-reviewer agent ◦ meaningfy-code-review |
| 7 | Merge deltas into the living specs | sync / archive |
spec-stewardship skill |
BDD scenario authoring is a design-phase activity (the
.featurefiles are a PLAN artifact the clarity gate scores for coverage); only step definitions are written at implement time.
Skillery is additive — it rarely conflicts, but it can overlap with plugins you already have.
Check what you have: on Claude Code, open the /plugin menu (or inspect enabledPlugins in
~/.claude/settings.json); on opencode, list installed plugins via its plugin manager (or inspect
opencode.json). The overlaps below are Claude-plugin overlaps (feature-dev, code-review are
@claude-plugins-official); on opencode they simply don't apply — the catalogue's skills are loaded
natively instead.
| Situation | What it is | What to do |
|---|---|---|
Old meaningfy-engineering / -ai-coding / -communication / -spine bundles |
the previous bundle cut | Migrate: uninstall them, install the new meaningfy-core + -building + -architecture + -consulting. |
feature-dev@claude-plugins-official |
official agents (code-architect/explorer/reviewer) overlapping epic-planner/implementer/code-reviewer |
Redundant, not breaking. Optionally disable feature-dev to avoid two voices on the same task. |
code-review@claude-plugins-official |
a read-only review runner | Keep — complementary: it runs, meaningfy-code-review is the checklist. |
commit-commands@claude-plugins-official |
commit/push/PR mechanics | Keep — meaningfy-git-workflow delegates to it. |
No stream-coding / ponytail |
mandatory external disciplines | Install them (see Installation §2). |
Worked example (a real setup). A machine running the old 3 meaningfy bundles +
feature-dev+code-review+commit-commands, missingstream-codingandponytail, needs: (1) migrate the 3 old bundles → the new 4; (2) installstream-coding+ponytail; (3) optionally disablefeature-dev; (4) keepcode-review+commit-commands. Nothing needs hard-removing — it's mostly renaming the bundles and adding the missing mandatory deps.
| Where | What | Read it when… |
|---|---|---|
docs/ai-coding/ |
the build-plane lifecycle + the /opsx runbook + DoD/quality gates + role playbooks |
you're learning how we build with agents |
docs/ai-sales/ |
the commercial engagement lifecycle, the sales runbook and DoD, and the sellable services catalogue (one page per Semantic Layer building block, or a named gap) | you're scoping or describing a commercial offering to a client |
docs/ai-consulting/ |
the Deep-tier advisory runbook, the consulting DoD, and the method docs (gap analysis, and four named-but-unowned technique stubs) | you're running or reviewing a Discovery & Onboarding Deep-tier engagement |
docs/roles-and-raci.md |
the six project roles and the RACI matrix, cited by every domain's playbooks | you want to know who is accountable for what |
docs/environment/ |
machine/tooling setup: external deps, the dual-CLI reference annex, the openspec/ setup guide |
you're installing or extending the catalogue |
spine/ |
the spec-backbone conventions (workflows, golden thread, lifecycle) | you're working with openspec/ / the spine |
docs/engineering-standards/ |
testing standard, project structure, coding prompt — these narrate; the operational rules are the code-principles catalogue | you want the durable engineering canon |
docs/philosophy/ |
the mindset behind it all | you want the why |
spec/ |
how to author a skill (governance + template) | you're contributing a skill |
Coming: the durable canon (
engineering-standards/,philosophy/, architecture/ADRs) will be published to GitHub Pages via AsciiDoc + Antora — skillery applying its own documentation standard to itself. Tracked as a follow-up (.claude/HARD-QUESTIONS.md).
skillery/
├── skills/ # flat: skills/<skill>/ (bundles group them in marketplace.json)
├── agents/ # three thin wrappers (no knowledge): epic-planner, implementer, code-reviewer
├── docs/ # ai-coding/ · ai-sales/ · ai-consulting/ · engineering-standards/ · philosophy/ · roles-and-raci.md · environment/
├── prompts/ # CLAUDE.md.template, global-prompt.md (AGENTS.md-canonical; CLAUDE.md is a thin pointer)
├── .opencode/ # GENERATED opencode tree (skills/agents/bundles); make generate-opencode — never hand-edit
├── spec/ # authoring spec, governance, skill-template.md, CREATING_SKILLS.md
├── spine/ # the spec-backbone conventions
├── openspec/ # live OpenSpec instance + forked `meaningfy` schema (skillery runs the spine on itself)
├── tools/ + tests/# the self-consistency validator (make validate)
└── .claude-plugin/# marketplace (4 role bundles)
See CONTRIBUTING.md and the Creating Skills guide.
Run make validate before opening a PR; CI runs it too. The governance method is in
spec/skill-repo-governance.md.
Apache 2.0 (see LICENSE); individual skills may carry their own LICENSE.txt. External
dependencies are attributed in THIRD_PARTY_NOTICES.md.
Open an issue, or contact the maintainers at info@meaningfy.ws.