Get moldea on skills.sh or read the complete documentation at skill.moldea.ai.
The latest release is 6.0.2. Install the latest version from main inside each repository that will use it:
npx skills add moldea-ai/skillFor a reproducible installation, pin the immutable release:
npx skills add "moldea-ai/skill#v6.0.2"Both commands install the portable skill named moldea. They do not install the CLI globally or require a hosted account. See Getting started for initialization, updates, and removal.
moldea keeps durable project context and agent behavior in a Git repository. Adopted projects own a canonical /moldea/** tree containing project truth, focused context, decisions, agent instructions, implementation relationships, runtime guidance, mirrors, and unresolved requirements.
The skill helps a coding agent:
- initialize the minimum useful project state when explicitly requested
- plan agent-enabled systems and decide what should remain ordinary software
- create and maintain grounded agents and reusable Agent Skills
- keep affected canonical knowledge aligned with implementation work
- evaluate, reconcile, repair, and structurally validate established state
After initialization, ask naturally to plan, build, review, or maintain AI agents, including model instructions and responsibilities in one-shot calls and workflows. Established project facts, approved policies, clear corrections, and project-context questions also receive bounded assessment without naming moldea or a file. Ordinary implementation requirements still use declared relationships, even when their effects will persist. When ordinary work expands to newly discovered paths, the coding agent checks those paths once at an existing scope checkpoint and preserves earlier matched owners. Only explicit initialization creates a new setup.
| Outcome | Example request |
|---|---|
| Initialize | Initialize moldea |
| Plan | Plan the agents for this project's support-triage workflow. |
| Create an agent | Create a support agent grounded in the current project policy. |
| Maintain context | Update moldea context for the approved refund policy. |
| Evaluate | Evaluate the current moldea project. |
| Reconcile | Reconcile the billing agent with its declared implementation. |
| Repair | Fix moldea. |
| Validate | Validate moldea. |
Evaluation is read-only. Repair corrects established errors without inventing policy, upgrading dependencies, or treating structural validity as proof that every behavior is correct.
| Need | Authority |
|---|---|
| Install, initialize, update, or remove the skill | Getting started |
| Understand activation, operations, evidence, and change boundaries | Workflow reference |
| Explore supported outcomes and examples | Capabilities and examples |
| Understand canonical project state and its repository layout | Project state and repository format |
| Plan an agent system | Planning agent systems |
| Design agents or Agent Skills | Designing agents and designing skills |
| Maintain or compress accumulated context | Continuous maintenance |
| Evaluate, reconcile, validate, or repair | Evaluate, reconcile, and validate |
| Inspect compatibility, local tooling, and resource limits | Compatibility and local tooling |
| Review instruction-loading behavior | Reference-reading checks |
| Run semantic evaluation or adapter qualification | Semantic evaluation, adapter qualification, and the qualification operator reference |
| Select fresh or pinned release evidence | Release evidence |
| Browse all public documentation | Documentation index |
Release 6.0.2 supports exactly:
- Git
>=2.30.0 - Node.js
>=22.11.0 - stable
@moldea.ai/corereleases satisfying^5.0.0 - stable
@moldea.ai/clireleases satisfying^9.0.0 - repository format version 1
- CLI JSON schema 5
The CLI must be a repository-root-local development dependency whose manifest declaration and installed stable version satisfy the supported range. The launcher also checks that installed Core satisfies both the CLI's declared Core range and moldea's supported range. The package manager and repository setup or CI own lockfile consistency; the launcher does not check target-project lockfiles. The skill never falls back to a global installation, another workspace, a package-manager launcher, or a transient download. Tooling establishment belongs only to authorized write-capable work. See Compatibility and local tooling for the complete launcher, machine-output, resource, and runtime contracts.
Initialization creates the minimum canonical foundation and uses the bundled deterministic writer to manage one README awareness block. That block tells repository-aware hosts to select the installed skill so its two-byte relevance gate can check known task paths. Selection is only a discovery bridge: a gate miss continues the host task without a CLI call, workflow-reference load, progress update, or final-report mention.
After adoption, clear AI-agent work and concrete project-level context use the adoption-only route. Explicit moldea operations, canonical paths, and changes inside the managed README block also activate directly. Other known task paths use declared relationship matching. Host planning, review, commit, and publication workflows keep control of their own procedures. Generic terminology, pasted proposals, temporary status, and lasting code changes alone do not establish direct relevance. Irrelevant work receives no moldea announcement or status.
Informational handoffs and read-only questions permit assessment, not automatic writes. A clear correction to established project truth authorizes its minimal canonical update after adoption and ownership checks, unless the request is read-only. Authorized updates preserve unrelated state and end with validation; they do not authorize implementation changes or broad context discovery.
The entrypoint keeps routing and essential boundaries compact. It loads only the operation-specific references needed for the selected work. Complete unchanged instructions may be reused while available; missing instructions after compaction must be read again, and summaries never replace instructions, repository evidence, or authorization. See the workflow reference and reference-reading checks.
Mechanical repository evidence uses the installed skill's closed launcher. It exposes bounded inspect, scope, content, validate, and composition operations without making canonical document bodies part of ordinary metadata output. Detailed invocation, pagination, failure, and runtime-compatibility behavior belongs to Compatibility and local tooling.
Semantic execution may project one fixed repository-root direct Node correctness-test invocation into aggregate pass/fail facts. Package-manager commands cannot contribute correctness evidence, and the projection never retains test names, assertions, paths, durations, or output bodies.
Before adoption, a non-repository informational question is answered without repository inspection. Only explicit initialization creates canonical project state. An explicit setup validation, evaluation, or inspection request can diagnose a failed adoption check with bounded read-only foundation inspection. Repair may recover an established but damaged setup with the required authority; neither route silently initializes an unrelated repository. If no independent host task remains after abstention, the coding agent reports only a neutral repository outcome. A changed topic resets relevance and authorization instead of inheriting them from earlier agent work.
For ordinary repository paths, the relevance gate accepts the relative spellings produced by Git, normalizes them to repository-logical paths, and emits only 0 or 1 without executing repository dependencies. The first check covers all host-known paths. A later check covers only materially new paths independently discovered during the host task; unchanged paths reuse their decision. A hit permits one bounded relationship query for its batch; it does not authorize loading every canonical record. The coding agent selects the smallest affected owner set, reads only the content needed for the task, and validates material canonical writes. An unrelated batch miss adds no moldea activity and does not erase an earlier matched owner.
Evaluation is read-only across ordinary repository files, Git state, configuration, submodules, the installed portable skill, and declared related repositories. Structural validation proves repository shape, not behavioral completeness. Claims still require repository evidence, and unresolved developer decisions remain explicit instead of being converted into invented policy.
Tooling establishment occurs only during authorized write-capable work and only after sufficient project context exists. Executable package-manager extensions stop automatic setup rather than being bypassed. Package identity and containment checks protect the launcher boundary, but they do not authenticate executable contents or provide an operating-system sandbox; the host's trust and execution controls remain authoritative.
moldea is a portable Agent Skill with deterministic conformance, semantic evaluation, adapter qualification, evidence publication, and documentation tooling. The website renders selected evidence snapshots and independently recorded mock-project runs. It has no evaluator responsibility.
| Area | Responsibility |
|---|---|
moldea/ |
Complete distributed Agent Skill: entrypoint, focused references, host metadata, managed README asset, and bounded generated scripts. |
src/ |
Maintained TypeScript for portable generation, isolated execution, semantic evaluation, evidence assets, release checks, and shared developer tooling. |
qualification/ |
Reviewed published compatibility snapshot, adapter profiles, and TypeScript execution. Attempts retain private local state below .evidence/. |
evidence/selection.json |
Independent maintainer selections for the semantic and qualification bundles shown on the website. |
website/ |
Static documentation and evidence presentation, including independently selected mock-project runs, sanitized session replays, and source links. |
fixtures/ |
Deterministic source fixtures and calibration records. Recorded evaluation and qualification attempts are not committed. |
docs/ |
Concise public concepts and durable workflows. API and HTTP endpoint documentation does not belong here. |
.github/workflows/conformance.yml |
Portable generation, runtime, path, release, and installation checks. |
.github/workflows/release-candidate.yml |
Exact package-candidate validation without publication. |
The distributed artifact is exactly moldea/; development-only tooling is not installed with the skill. Run npm run matcher:generate after changing the relevance gate's locked inputs and npm run matcher:check to verify the committed artifact.
Repository development requires Node.js ^24.15.0 and npm >=10.9.0. The distributed moldea/ artifact keeps its documented Node.js >=22.11.0 runtime contract.
Install every workspace dependency from the repository root without lifecycle scripts:
npm ci --ignore-scriptsTo prepare an exact published CLI release, run npm run release:update-cli -- <version>. The updater verifies the published CLI, installs its locked dependency closure in a temporary directory, regenerates portable scripts from maintained TypeScript, and checks release identity before completing. It restores files it changed if preparation or verification fails, while preserving concurrent edits. Run npm ci --ignore-scripts afterward to bring local dependencies in line with the updated lockfile before running conformance checks.
The private qualification workspace installs its exact pnpm 11.27.1 dependency through this command. Qualification invokes that copy directly; a globally installed pnpm is not required.
After packages are published, refresh the reviewed qualification catalog with npm run qualification:compatibility:update, inspect and commit qualification/compatibility/snapshot.json, then run npm run qualification:compatibility:check before paid qualification. Ordinary qualification commands use the committed local snapshot and do not need an adjacent packages checkout.
Both the root tooling and the website consume Website UI 1.13.0 with its exact Astro 7.2.8 peer. Normal dependency resolution selects that version without an override.
Run the deterministic boundaries:
npm run runtime:build
npm run portable:check
npm run test:unit
npm run test:integration
npm test
npm run qualification:test
npm run qualification:compatibility:check
npm run typecheck
npm run lint
npm run format:check
npm run qualification:typecheck
npm run qualification:lint
npm run qualification:format:check
npm run path:check
npm run docs:check
npm run website:checknpm test includes the website browser suite. Production website:build, release:check, and Pages deployment require both evidence selections to be populated and prepared. Development website checks exercise both the clean current catalogs without recorded results and isolated synthetic evidence.
Specialized workflows have focused operator references:
| Workflow | Start here |
|---|---|
| Resource profiles and calibration | Compatibility and local tooling |
| Semantic preflight, diagnosis, recording, and verification | Semantic evaluation |
| Custom and adapter qualification, batches, and diagnosis | Adapter qualification and qualification operator reference |
| Fresh or explicitly pinned release evidence | Release evidence |
The skill uses independent semantic versioning. Every release must:
- record its exact version in
moldea/SKILL.md - declare the compatible CLI major; evidence-backed production releases also bind the exact evaluated CLI closure plus CLI JSON schema in release evidence
- pass current conformance; evidence-backed production releases also select verified fresh or explicitly pinned semantic and qualification evidence independently
- preserve identical
moldea/bytes across official distribution channels - use an immutable
v<version>tag
During prelaunch testing, skill tags require deterministic conformance, synchronized release identity, and installation checks. Semantic evaluations and adapter qualifications are separate evidence-backed assurance; a passing tag does not establish them. Release 6.0.2 selects passing semantic and qualification evidence for the production website and npm run release:check. See Release evidence for the exact workflows.