{
  "markdown": "<!-- mcp-name: cx.alloy/alloy -->\n\n# Work with Alloy\n\n## About Alloy\n\nAlloy is an AI-native workspace where your team and AI agents collaborate — sharing artifacts, knowledge, skills, and access to external systems, all on one foundation. Connect Claude, Codex, or Gemini — or spawn Alloy cloud agents — and let them coordinate with each other and your teammates.\n\nStart free at [alloy.cx](https://alloy.cx) · Docs: [alloy.cx/docs](https://alloy.cx/docs)\n\n---\n\nThis plugin teaches any AI agent to use Alloy as its source of truth and gives it reusable Alloy-specific operating skills — reading shared knowledge before answering, writing durable notes and artifacts, creating workflows, running operational reviews, and spawning autonomous agents.\n\nThe shared source of truth is the `work-with-alloy` skill. Platform-specific\nplugin manifests are thin wrappers around the same skill content.\n\n## Use Cases\n\nUse Alloy as an AI agent's shared operating layer for work with humans and other\nagents, including Claude, Codex, Alloy cloud agents, and other AI\nagents.\n\n- Read shared organizational knowledge before answering: company docs,\n  decisions, knowledge notes, communication history, and context maintained by\n  all AI agents and humans.\n- Write durable artifacts back to Alloy: proposals, research, summaries, specs,\n  logs, decisions, and reusable notes that future agents can pick up.\n- Access approved business systems through Alloy-controlled MCP: the agent\n  connects once to Alloy, while Alloy governs which upstream MCPs, APIs, files,\n  secrets, and actions are available.\n- Work across connected tools without each agent configuring every integration\n  separately: CRM, support, docs, calendars, email, databases, internal systems,\n  and private gateways.\n- Call Alloy cloud AI agents for delegated work, then continue from their\n  outputs and artifacts.\n- Create or configure Alloy AI teammates, instruction skills, and executable workflows so repeatable\n  work becomes a governed organizational process.\n- Coordinate multi-agent operations where AI agents hand off tasks through\n  MCP/API triggers.\n- Keep organizational learning portable across agents: knowledge, artifacts,\n  access rules, and audit trail.\n\n## Layout\n\n- `skills/work-with-alloy/` - core source-of-truth skill.\n- `skills/review-alloy-operations/` - operational review skill for auditing teammates, instruction skills, workflows, MCPs, and recent activity.\n- `skills/*/references/` - supporting playbooks loaded by each skill.\n- `skills/*/agents/openai.yaml` - Codex/OpenAI skill UI metadata.\n- `skills/work-with-alloy/assets/` - shared skill UI assets such as the Alloy icon.\n- `.codex-plugin/plugin.json` - Codex plugin manifest.\n- `.claude-plugin/plugin.json` - Claude Code plugin manifest.\n- `.mcp.json` - Alloy hosted MCP configuration using `ALLOY_TOKEN`.\n\n## Shared Skill\n\nThe skills under `skills/` are intended to stay host-neutral. Update the shared\nskill content there instead of maintaining separate Claude and Codex instruction\ntrees.\n\n## Prerequisites\n\nThese apply to anyone installing the plugin into Claude Code or Codex.\n\n### 1. `ALLOY_TOKEN` environment variable\n\nThe bundled `.mcp.json` reads the Alloy MCP bearer from `ALLOY_TOKEN`. Export\nit in the host shell before starting Claude Code or Codex:\n\n```\nexport ALLOY_TOKEN=\"<your-alloy-token>\"\n```\n\nGet a token at https://alloy.cx/docs/reference/tech-docs/hosted-mcp.\n\n### 2. Host restart after install\n\nThe plugin's MCP server is loaded by the host at startup. After installing or\nupdating the plugin, restart the host so it can load the bundled MCP config.\n\n## Codex\n\nThe Codex plugin manifest references `./skills/` and `./.mcp.json`.\n\nSet `ALLOY_TOKEN` in the host environment before using the bundled MCP config.\n\nMarketplace registration and app-server install have been validated with Codex\n0.125.0:\n\n```bash\ncodex plugin marketplace add Alloy-Systems/alloy-marketplace\n```\n\nCodex installs `work-with-alloy` from the marketplace entry pointing at a tagged\nrelease. After install, Codex reports the plugin as enabled and exposes the\n`work-with-alloy:work-with-alloy` skill plus the bundled `alloy` MCP server.\n\n## Claude Code\n\nThe Claude plugin manifest at `.claude-plugin/plugin.json` references the same\n`./skills/` and `./.mcp.json` as the Codex side. Install flow once the Alloy\nmarketplace is published:\n\n```\n/plugin marketplace add Alloy-Systems/alloy-marketplace\n/plugin install work-with-alloy@alloy-marketplace\n```\n\nClaude Code's plugin installer clones plugin source from GitHub over SSH by\ndefault. Before `/plugin install`, make sure one of these is true:\n\n- A working GitHub SSH key on this machine (test: `ssh -T git@github.com`).\n- A global git URL rewrite that pushes plugin clones through HTTPS:\n\n  ```\n  git config --global url.\"https://github.com/\".insteadOf \"git@github.com:\"\n  ```\n\nSet `ALLOY_TOKEN` in the host environment before using the bundled MCP config.\n\nAfter install, restart Claude Code and confirm registration:\n\n```\nclaude mcp list   # expect plugin:work-with-alloy:alloy as connected\n```\n\n## Versioning policy\n\nThis project follows **semantic versioning** with synchronized releases across\nClaude Code and Codex wrappers. A single version applies to the whole release:\nthe shared skill content in `skills/work-with-alloy/`, both `plugin.json`\nmanifests, the `.mcp.json` config, and this README. Both\n`.codex-plugin/plugin.json` and `.claude-plugin/plugin.json` always carry the\nsame `version` field.\n\n### Semver semantics for this plugin\n\n| Bump | What it means | Examples |\n|------|---------------|----------|\n| **Patch** (`0.1.0` → `0.1.1`) | Cosmetic only. Typo, wording tweak, broken link, clarification. No change in how the agent behaves. | Fix a typo in `SKILL.md`. Update a stale URL in `references/`. |\n| **Minor** (`0.1.0` → `0.2.0`) | Backward-compatible addition. New rule, new Quick Reference row, new reference playbook, new optional manifest field. Prior usage still works. | Add a new rule to Core rules. Add a new entry to a Quick Reference table. Add a new playbook under `references/`. |\n| **Major** (`0.x` → `1.0`, `1.x` → `2.x`) | Breaking change. A canonical path, file name, required field, or required rule changes in a way that prior consumers may break. | Rename `Personal/<username>/.knowledge/knowledge.md` to a different path. Remove a Core rule. Restructure `references/` so existing links break. |\n\nPre-1.0 (`0.x`) signals \"still stabilizing - minor bumps may include breaking\nchanges\". The `1.0.0` line will be cut when the canonical paths and Core rules\nare confirmed stable.\n\n### Release flow\n\n1. Work happens on feature branches, merged into `main` via PR.\n2. When `main` is in a state worth releasing, bump both\n   `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json` `version`\n   fields in the same commit.\n3. Cut a git tag on the merge commit: `git tag vX.Y.Z && git push origin vX.Y.Z`.\n4. Bump the corresponding `ref` field in the `Alloy-Systems/alloy-marketplace` repo's\n   `marketplace.json` entry for `work-with-alloy`. Users receive the new\n   version through `/plugin update` only after this marketplace bump.\n5. Untagged commits on `main` are visible to anyone reading the repo but are\n   not delivered through `/plugin install` or `/plugin update` until the\n   marketplace points at a new tag.\n\n### Cadence\n\nTags are cut per logical release, not on every commit. A typical trigger is a\nnew Core rule landing, a new reference playbook being added, or a breaking\nrestructure being completed and ready to ship. Cosmetic-only changes can\naccumulate in `main` and be released as a patch bump when convenient.\n\n## License\n\nApache License 2.0.\n",
  "bytes": 7682,
  "sha": "fc7c5c74ba64cd8ca4c6cf9467f0b4968d11cbd1f7fc1cf5d384878f20e9ae6f",
  "repo_slug": "alloy-systems/work-with-alloy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_cx_alloy_alloy_6abc8491/readme"
}