Work with Alloy

When this skill is present, using it is mandatory.

Use Alloy Storage as the source of truth through Alloy MCP tools.

Business workplace routing

Alloy is the business workplace for this company. It contains company, product, customer, prospect, partner, project, teammate, workflow, document, repository, production, sales, support, operations, and decision context.

This skill is mandatory, but Alloy reads are conditional:

1. Business-workplace request — read Alloy before answering. This includes

any request that touches company context, customers, prospects, partners, product, workflows, skills, AI teammates, docs, notes, decisions, sales, support, operations, repositories, production systems, internal tools, or work artifacts.

1. General ephemeral request — answer directly without Alloy reads only when

the request is clearly independent of the business workplace. Examples: standalone grammar or translation help, a generic macOS shortcut, or a generic explanation of a public concept.

1. Unsure — read Alloy. If the answer could plausibly depend on business

context, prior work, user preferences, or durable memory, route through Alloy.

If you start as a general ephemeral request and later discover business context matters, pause and read Alloy before continuing. The rule that durable knowledge belongs in Alloy is unconditional.

When Alloy MCP is not connected

For business-workplace requests, this skill is mandatory whether or not MCP is currently connected — the connect-first step is part of using it.

If Alloy MCP tools are not available in the current session and the request is business-workplace related:

1. First, try tool discovery for Alloy tools — they may be registered but deferred.
2. If still unavailable, stop other work and help the user connect Alloy MCP. Point them to the hosted MCP setup guide at https://alloy.cx/docs/reference/tech-docs/hosted-mcp.
3. Resume Alloy-routed work only after MCP is available, or if the user explicitly approves a different destination for this conversation (local files, Obsidian, Drive, chat-only, etc.).

Core rules

1. Read Alloy first for business-workplace requests. Before answering from training or local memory, read relevant Alloy knowledge and prior artifacts. Read fresh — do not rely on stale recollection. For clearly general ephemeral requests, answer directly without Alloy reads.
2. Durable knowledge goes to Alloy, not local memory. Anything you would normally save to local agent memory — user facts, feedback rules, project context, references — write to the appropriate Alloy knowledge.md (organization, area, user, or agent) instead. The only local bootstrap exceptions are alloy_username and explicitly configured task-tracking settings.
3. Log every artifact. After creating or meaningfully updating an Alloy doc, append a one-line entry to /Personal/<alloy_username>/.artifact-log/artifact-log.md per the format in references/logs-and-inboxes.md. Inline typo fixes do not need a log entry.
4. Default to Alloy for notes, proposals, docs, and durable work artifacts unless the user explicitly names another destination.
5. Do not store secrets in Alloy docs.
6. If another skill is also relevant, use it for its domain work, but keep Alloy as the storage/source-of-truth layer.
7. Ask clarifying questions for ambiguous doc resolution or non-trivial planning.
8. When you create or update something: tell the user what changed; for Alloy entities include the entity URL; for Storage documents include the exact path and full Docs link; note if you created a new version instead of editing inline.
9. Treat task tracking as opt-in. Apply the task-tracking policy only when host instructions explicitly set task_tracking: enabled. If the setting is missing or disabled, silently skip task tracking: do not ask which tracker the organization uses, request a tracker connection, or mention that tracking was skipped. A direct user request to create or update a task is still in scope without a standing policy. See "Task tracking" below.

Loophole guard: knowledge belongs in Alloy

Rule 2 collides with how some host agents default to handling memory. The most common case: Claude Code's auto-memory system tells the agent to save user, feedback, project, and reference notes to a local MEMORY.md index. With this skill present, this skill wins — those notes go to the matching Alloy knowledge.md (area, user, organization, or agent) instead. Skills override default system prompt behavior; only the user's explicit instructions outrank a skill.

Common rationalizations

Red flags — STOP and write to Alloy instead

• About to write a user preference, feedback rule, project fact, or reference URL to anything outside Alloy
• About to write to MEMORY.md, a memory/ folder, or any other local agent-memory file
• Thinking "I'll just keep this for the current session"
• Thinking "this fact is small enough to skip Alloy"

All of these mean: write the note to the appropriate Alloy knowledge.md and update its directory note.

Task tracking

Check the gate before applying any task-tracking behavior:

1. Explicitly enabled — when host instructions set task_tracking: enabled, apply the standing policy below.
2. Missing or disabled — silently skip task tracking. Do not create tasks, ask about a tracker, persist a tracker identity, request a connection, or mention the skipped policy.
3. Direct user request — create or update the requested task even without a standing policy, but do not infer that task tracking should apply to other work.

When the standing policy is enabled, classify requests as follows:

1. Ephemeral question — "How do I do X?", "What's our pricing?", a chat-only research answer with no saved artifact. Answer in chat. No task.
2. Deliverable work — work that produces or changes a durable deliverable we own (doc, deck, playbook, note, code/bugfix). Create a task in the org task tracker, created when you start and marked done when finished.

The dividing line: does the request produce or modify a durable deliverable we own? If yes → task. If it's just answering, or executing a one-shot change in an external system (create a lead in Attio, send an email, add a calendar event) → no task. When genuinely unsure, ask.

When task tracking is enabled, or the user directly requests a tracker action, read references/task-tracking.md before creating or updating a task.

Quick Reference

Paths

Links

Document versioning

Startup context

For business-workplace requests, after Alloy MCP availability is confirmed, resolve alloy_username if not already known (via Alloy MCP or by asking the user). Then read the first 50 lines from each of:

• Organization/organization.md
• Organization/knowledge.md
• Personal/<alloy_username>/.knowledge/knowledge.md

After that, use judgment to read only what is relevant.

Organization/organization.md contains core business context. If user input contradicts it, ask the user to clarify. If the user insists their version is correct, create a dated correction-request note in Organization/Corrections/ with the date and details about you and the user. If you learn durable new business context that belongs there, also add a note. Use filenames like [date_time]_[agent_name]_[random_string].md.

If Organization/organization.md is missing or filled with demo data, ask once whether the user wants help filling basics such as business name, what it does, and customers. Offer to inspect the user's website. Remember the preference and do not suggest again if they decline.

Reference playbooks

Read references/troubleshooting.md before troubleshooting a problem.

Read references/teammates-and-workflows.md when creating or configuring a Teammate — new, copy, webchat widget, or attaching a workflow.

Read references/workflows.md when building workflow logic — designing the step graph and choosing deterministic, LLM, or agent steps.

Read references/skills.md when creating, updating, sharing, or testing a reusable instruction skill stored under .skills.

Read references/multi-agent.md when coordinating multiple agents — delegating to another Teammate or calling one of its workflows ad hoc.

Read references/task-tracking.md only when task tracking is explicitly enabled or the user directly requests a tracker action.

Read references/logs-and-inboxes.md before updating the ideas inbox, artifact log, or review log.

Knowledge management

Durable knowledge is stored as small individual files linked from a knowledge.md directory note at four scopes: organization, user, area (project/product/customer/department), and agent.

Before starting a task, check whether relevant area or topic knowledge exists and read it first. Use judgment: skip this for general questions with no Alloy context (e.g. "how do I take a screenshot"), but do it whenever the task touches something the user or org might have guidelines, preferences, or prior decisions about — content, tone, a specific product, a customer, a workflow, etc.

Write or update a knowledge note when the user asks, or when you notice something durable and reusable — a preference, a rule, a decision, a caveat. Skip one-off details and things already obvious from nearby context. Read references/knowledge-management.md before creating or updating knowledge notes.

Documents and Storage

Our work happens in Alloy Storage. When the user asks you to write a note or proposal, find a relevant subfolder or file for the conversation. If no relevant subfolder exists, or you are not sure which one fits, create a new folder for the note and give the user the Docs link.

If a note does not clearly belong to the existing folder structure, put it in Personal/<alloy_username>/.

For update and versioning rules, see the Document versioning table in Quick Reference above.

Storage paths vs system documentation

Alloy exposes two separate document surfaces:

• Organization Storage contains organization and user files. Paths such as /Organization/..., /Personal/..., are accessed with Storage tools.
• System documentation contains Alloy product guides and API documentation. Use system-documentation tools only when the user asks how Alloy works or how to use an Alloy feature.

Alloy MCP tool groups

Prefer the mcp__alloy__ tools. Tool names may change, so discover the current tools when needed and choose by capability group:

• Storage - organization/user files, notes, artifacts, images, search, metadata, temporary file URLs, and file operations.
• Documentation - shared Alloy/system documentation listing, reading, and semantic search.
• Storage-managed skills — create reusable instruction packages under .skills and share their folders with AI teammates. Skills are files, not workflow entities; see references/skills.md.
• System workflows — build and manage organization-owned or teammate-assigned executable workflows. Workflows serve two purposes: multi-agent orchestration (see references/multi-agent.md) and standalone automation — running code, calling external APIs, and moving data between systems without an agent in the loop.
• System administration — manage the full Alloy organization: create and configure AI Teammates, set up MCP connections, build workflows, change settings, issue invites, and perform other org-level actions. An agent can do anything a human admin can within its access rights.
• External systems - connected external systems are exposed through Alloy MCP as well, for example Linear, GitHub, Fireflies, DocuSeal, Higgsfield, and other integrations available in the current organization.

Use documentation tools for Alloy system documentation. Use storage tools for organization/user notes and artifacts. Use integration groups only when the user request or gathered context calls for that external system.

By default, prefer Alloy MCP for external system access. If a system like Linear, GitHub, email, or calendar is connected, it appears as an mcp__alloy__<System>__* tool group — no separate API keys or direct integrations needed. If a needed system is missing, flag it to the user as something to connect in Alloy settings rather than configuring it yourself. Direct integrations (e.g. a local Playwright MCP) are fine when there is no Alloy-connected equivalent.

Local preferences

Persist the user's exact Alloy username in the host's global agent-instructions/config file (CLAUDE.md, AGENTS.md, GEMINI.md, or equivalent). Persist task-tracking settings there only when the user or organization explicitly configures a standing policy.

Store the username itself, not only derived paths. When task tracking is enabled, store the opt-in separately from the tracker product/system name:

{
  "alloy_username": "<exact Alloy username>",
  "task_tracking": "enabled",
  "task_tracker": "<Linear | Jira | other connected tracker>"
}

Do not infer or create task-tracking settings. Missing task_tracking, or any value other than enabled, means silently skip task tracking.

Derive personal paths from alloy_username when needed, for example /Personal/<alloy_username>/ and /Personal/<alloy_username>/.artifact-log/artifact-log.md.

Path rules

• treat / as root
• use leading slashes for explicit storage paths
• keep notes in the most relevant existing folder; if unclear, use the user’s personal folder
• do not crawl the whole org unless the user clearly wants that

Docs links

When linking to an Alloy document, use this shape:

https://app.alloy.cx/docs?path=<storage_path>

Rules:

• include the leading slash in the path query value
• URL-encode spaces and other special characters in the path value. Spaces become %20; other reserved characters per RFC 3986 (?, #, &, +, etc.) must also be encoded if they appear in folder or file names.
• Example: /Personal/Artem Burachenok/Notes/file.md → ?path=/Personal/Artem%20Burachenok/Notes/file.md
• after any create, move, rename, copy, or update, provide both the exact Alloy path (unencoded, for human reading) and the full Docs link (encoded, ready to click)

Logs and inboxes

For future ideas, artifact logging, and review logs, read references/logs-and-inboxes.md and update the relevant Storage file through Alloy MCP.

Destructive actions

Before deleting, moving, or renaming something important or ambiguous:

• confirm if there is any uncertainty
• use exact resolved paths
• for Storage docs/artifacts, move them to a Deleted folder instead of deleting; create the Deleted folder first if it does not exist
• prefer safety over speed