# How Automation Prompt Actions Handle @mentions for Sources and Skills in Craft Agents

> Discover how automation prompt actions resolve @mentions for sources and skills in Craft Agents. Learn about regex parsing, registry resolution, and prompt injection for LLMs.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-03

---

**Automation prompt actions parse @mentions using a regex-based tokenizer, resolve them against source and skill registries, deduplicate the results, and inject the resolved references into the execution environment before sending the prompt to the LLM.**

In the Craft Agents OSS framework, automation prompt actions enable dynamic interactions with external data sources and reusable instruction sets through simple @mentions. Understanding how these mentions are processed—from initial parsing to final resolution—is essential for building reliable AI automations. This article examines the complete flow implemented in the craft-ai-agents/craft-agents-oss repository.

## Parsing @mentions with parsePromptReferences

The process begins in [`packages/shared/src/automations/utils.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/utils.ts) where the **`parsePromptReferences`** utility scans prompt strings for valid mention tokens. The function employs a global regular expression `/(?:^|[\s(])@([a-zA-Z][a-zA-Z0-9-]*)/g` that identifies `@` symbols preceded by the start of string, whitespace, or an opening parenthesis, followed by alphanumeric characters and hyphens.

The utility returns a **`PromptReferences`** object containing a deduplicated, lower-cased array of mention slugs. This normalization ensures consistency across the resolution pipeline, regardless of how users format their prompts.

```typescript
import { parsePromptReferences } from '@craft-agent/shared/automations';

// Example prompt from a user
const prompt = `
  @github Please list the latest pull requests.
  Also, @my-skill can help with the summary.
`;

const refs = parsePromptReferences(prompt);
// refs.mentions => ['github', 'my-skill']

```

## Resolving Mentions Against Registries

Once parsed, the RPC handler in [`packages/server-core/src/handlers/rpc/automations.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server-core/src/handlers/rpc/automations.ts) (publicly exposed via `@craft-agent/shared/automations`) processes each mention through a resolution cascade. For every slug in the mentions array, the system performs two checks:

- **Source Registry Check**: The handler queries `packages/server-core/src/sources/...` to verify if a source with the matching slug exists and is currently active.
- **Skill Registry Check**: If no source matches, the system falls back to `packages/shared/src/skills/...` to locate a skill definition.

Successfully resolved mentions are stored as `ResolvedReference` objects containing the type ('source' or 'skill') and the normalized slug. Unresolved mentions trigger user-visible errors such as "Source 'xyz' is not active. Activate it by @mentioning it in your message..."

```typescript
// In the RPC handler (simplified)
async function resolveMentions(refs: PromptReferences) {
  const resolved: ResolvedReference[] = [];
  for (const slug of refs.mentions) {
    if (await sourceRegistry.isActive(slug)) {
      resolved.push({ type: 'source', slug });
    } else if (await skillRegistry.exists(slug)) {
      resolved.push({ type: 'skill', slug });
    } else {
      throw new Error(`Could not resolve @${slug}`);
    }
  }
  return resolved;
}

```

## Deduplication and Automation Naming

The `parsePromptReferences` utility already removes duplicates from the mentions array, allowing the resolver to process each unique slug exactly once. This guarantees idempotent behavior even when users reference the same source or skill multiple times in a single prompt.

Additionally, [`packages/shared/src/automations/name-utils.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/name-utils.ts) provides fallback naming logic for automations that lack explicit `name` fields. When no name is specified, the engine derives the automation name from the first @mention in the prompt, producing deterministic identifiers like "@linear-automation" for prompts beginning with "@linear".

## Execution Environment and Prompt Handling

The final stage occurs in [`packages/shared/src/automations/handlers/prompt-handler.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/handlers/prompt-handler.ts), where resolved mentions are injected into the execution environment. The handler performs three critical operations:

1. **Source Data Loading**: Resolved source slugs trigger data fetching (e.g., recent GitHub commits or Linear tickets) that the LLM can reference.
2. **Skill Instruction Loading**: Resolved skill slugs load reusable instruction sets that modify the LLM's behavior.
3. **Variable Expansion**: The handler expands `${VAR}` placeholders using `buildEnvFromPayload` before sending the fully-resolved prompt to the model.

This ensures the LLM receives a concrete prompt where abstract @mentions have been transformed into contextual data and specific instructions.

## Summary

- **`parsePromptReferences`** in [`packages/shared/src/automations/utils.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/utils.ts) tokenizes prompt strings using the regex `/(?:^|[\s(])@([a-zA-Z][a-zA-Z0-9-]*)/g` to capture valid @mentions.
- The RPC handler in [`packages/server-core/src/handlers/rpc/automations.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server-core/src/handlers/rpc/automations.ts) resolves mentions against source and skill registries, generating errors for inactive or missing references.
- Deduplication occurs at parse time, ensuring each slug is processed once regardless of repetition in the prompt.
- Automation names fall back to the first @mention when not explicitly defined, utilizing logic in [`packages/shared/src/automations/name-utils.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/name-utils.ts).
- The prompt handler in [`packages/shared/src/automations/handlers/prompt-handler.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/handlers/prompt-handler.ts) injects resolved data into the execution environment and expands variables before LLM invocation.

## Frequently Asked Questions

### What regex pattern does Craft Agents use to detect @mentions?

The framework uses the pattern `/(?:^|[\s(])@([a-zA-Z][a-zA-Z0-9-]*)/g` which matches `@` symbols at the start of a string or preceded by whitespace/opening parentheses, followed by alphanumeric characters and hyphens. This ensures that email addresses and other @-prefixed strings are not falsely detected as mentions, while allowing hyphens in valid source and skill slugs.

### How does the system handle duplicate @mentions in the same prompt?

The `parsePromptReferences` utility automatically deduplicates mentions before returning the `PromptReferences` object. This means the resolution logic processes each unique source or skill slug exactly once, preventing redundant data fetching and instruction loading during automation execution.

### What happens if an @mention references an inactive source?

When a mention resolves to a source that exists but is not active, the system throws a user-visible error with the message format "Source 'xyz' is not active. Activate it by @mentioning it in your message..." This validation occurs in the RPC handler at [`packages/server-core/src/handlers/rpc/automations.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server-core/src/handlers/rpc/automations.ts) before any automation action executes.

### Can automation names be generated automatically from @mentions?

Yes. If an automation definition lacks an explicit `name` property, the system derives the name from the first @mention in the prompt using the logic in [`packages/shared/src/automations/name-utils.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/name-utils.ts). For example, a prompt starting with "@linear review tickets" generates an automation named "@linear-review-tickets", providing deterministic identification for unnamed automations.