Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Emanuele-web04/synara/llms.txt

Use this file to discover all available pages before exploring further.

Skills and mentions are two ways to give agents structured, reusable context without copying and pasting the same instructions into every message. Skills are Markdown files containing prompt instructions that get injected into a session when you select them. Mentions are @-style references that direct a message to a specific provider or file path. Both are selected from the composer using autocomplete pickers.

​
What skills are

A skill is a Markdown file containing instructions for an agent — a coding style guide, a project architecture overview, a testing convention, or any other reusable guidance you want the agent to follow. Skills are named and scoped so you can have provider-specific variants and project-local overrides. Skills are described by ProviderSkillDescriptor: 
// From providerDiscovery.ts
export const ProviderSkillDescriptor = Schema.Struct({
  name: TrimmedNonEmptyString,
  description: Schema.optional(TrimmedNonEmptyString),
  path: TrimmedNonEmptyString,
  enabled: Schema.Boolean,
  scope: Schema.optional(TrimmedNonEmptyString),
  interface: Schema.optional(ProviderSkillInterface),
  dependencies: Schema.optional(Schema.Unknown),
});

export const ProviderSkillInterface = Schema.Struct({
  displayName: Schema.optional(TrimmedNonEmptyString),
  shortDescription: Schema.optional(TrimmedNonEmptyString),
});
The scope field identifies where the skill came from: "synara" (portable, from ~/.synara/skills), "codex", "claude", "cursor", "gemini", "grok", "kilo", "opencode", "pi", "agents", or "project" (from a .synara/skills or .codex/skills folder in the repository).

​
How skills are discovered

Synara walks a priority-ordered set of directories to build the skills catalog. The order is designed so that provider-native skill copies win over portable ones for the active provider, and earlier entries in the list take precedence over later ones on name conflicts. The catalog aggregates skills from all configured origins in this default order: 
synara → codex → claude → cursor → gemini → grok → kilo → opencode → pi → agents
For a given active provider, the preferred origins are promoted to the front. For example, when using Claude Code the claude origin is promoted first, so .claude/skills entries shadow same-named skills from ~/.synara/skills. Home-directory roots:
OriginPath
synara~/.synara/skills
codex~/.codex/skills
claude~/.claude/skills
cursor~/.cursor/skills-cursor, ~/.cursor/skills
gemini~/.gemini/skills
grok~/.grok/skills
kilo~/.kilo/skills
opencode~/.config/opencode/skills
pi~/.pi/agent/skills
agents~/.agents/skills
Project-level roots are discovered by walking up the directory tree from the project’s working directory, looking for .<origin>/skills folders inside each ancestor directory.
The ~/.synara/skills directory is created automatically on first use. Drop a SKILL.md file in a named subdirectory there (e.g., ~/.synara/skills/my-conventions/SKILL.md) and it will appear in the skills picker for every project and provider.

​
Skill file format

Each skill is a Markdown file named SKILL.md (or any .md file when the root allows plain Markdown files, as Pi does). Synara reads a small YAML frontmatter block to extract metadata: 
---
name: typescript-style
description: TypeScript coding conventions for this project
display-name: TypeScript Style
short-description: Enforce strict TS conventions
---

Always use `const` over `let` when the variable is never reassigned.
Prefer explicit return types on all exported functions.
Avoid `any`; use `unknown` and narrow the type before use.
Supported frontmatter keys:
KeyDescription
nameCanonical identifier; used for deduplication (case-insensitive)
descriptionFull description shown in detail views
display-nameHuman-readable label shown in the picker
short-descriptionOne-line summary shown beneath the skill name in the picker
disable-model-invocationSet to true to disable this skill by default

​
How skills are injected into provider sessions

When you select a skill in the composer and send a message, the ProviderSkillReference is attached to the turn: 
// From providerDiscovery.ts
export const ProviderSkillReference = Schema.Struct({
  name: TrimmedNonEmptyString,
  path: TrimmedNonEmptyString,
});
For providers that natively support skill files (such as Claude Code reading .claude/skills or Codex reading .codex/skills), Synara passes the file path directly and the provider loads it. For providers without native skill support — including Gemini, Grok, Kilo, and OpenCode — Synara reads the skill file and inlines its content into the turn as an XML-tagged block: 
The user invoked the following agent skill(s) for this request. Follow each
skill's instructions. File paths referenced inside a skill are relative to its
"dir" attribute.

<skill name="typescript-style" dir="/Users/you/.synara/skills/typescript-style">
...skill content...
</skill>
Each inlined skill is capped at 24,000 characters to avoid overflowing the provider’s turn budget. If multiple skills are selected and the total would exceed the turn’s character limit, Synara includes as many skills as fit and silently truncates the rest.

​
Disabling skills with SkillsServerSettings

Skills can be disabled globally in settings so they never appear in the picker and are never injected. The SkillsServerSettings.disabled array holds a list of skill names (matched case-insensitively): 
// From settings.ts
export const SkillsServerSettings = Schema.Struct({
  disabled: DisabledSkillNames,  // Schema.Array(Schema.String.check(Schema.isMaxLength(256)))
});
To disable a skill, open Settings → Skills and toggle it off. The skill’s name is added to settings.skills.disabled. You can also edit ~/.dpcode/userdata/settings.json directly: 
{
  "skills": {
    "disabled": ["typescript-style", "verbose-explanations"]
  }
}
Disable skills you do not use to keep prompts focused and avoid spending token budget on irrelevant instructions. A skill that expands to 2,000 tokens of conventions is only useful when those conventions apply to the task at hand.

​
Slash commands in the composer

The composer supports /command triggers for built-in Synara actions. Type / in the composer to open the slash command menu:
CommandDescription
/clearStart a fresh thread and clear the current conversation context
/compactCompact the current thread context to free space
/modelSwitch the response model for this thread
/planSwitch this thread into plan mode
/defaultSwitch this thread back to normal chat mode
/reviewStart a code review for current changes
/forkFork this thread into local or a new worktree
/sideOpen a guarded Side from this thread
/statusShow context usage and rate-limit status
/subagentsInsert a prompt that asks the assistant to delegate work
/fastTurn fast mode on or off for this thread
The available slash commands vary by provider. Claude Code handles most slash commands natively (via its own / UX), so Synara only surfaces /side as an app-level command when Claude Code is active. Other providers like Codex get the full list above.

​
Mentions in the composer

Mentions let you reference a provider or a path directly in a message using @name syntax. When you type @ in the composer, the mention picker opens and shows discoverable items. A mention resolves to a ProviderMentionReference: 
// From providerDiscovery.ts
export const ProviderMentionReference = Schema.Struct({
  name: TrimmedNonEmptyString,
  path: TrimmedNonEmptyString,
});
Mentions are attached to the turn message alongside skills: 
// From orchestration.ts — ThreadTurnStartCommand message shape
message: Schema.Struct({
  messageId: MessageId,
  role: Schema.Literal("user"),
  text: Schema.String,
  attachments: Schema.Array(ChatAttachment),
  skills: Schema.optional(Schema.Array(ProviderSkillReference)),
  mentions: Schema.optional(Schema.Array(ProviderMentionReference)),
}),
Provider mention support is declared in ProviderComposerCapabilities: 
export const ProviderComposerCapabilities = Schema.Struct({
  provider: ProviderDiscoveryKind,
  supportsSkillMentions: Schema.Boolean,
  supportsSkillDiscovery: Schema.Boolean,
  supportsNativeSlashCommandDiscovery: Schema.Boolean,
  supportsPluginMentions: Schema.Boolean,
  supportsPluginDiscovery: Schema.Boolean,
  supportsRuntimeModelList: Schema.Boolean,
  supportsThreadCompaction: Schema.optional(Schema.Boolean),
  supportsThreadImport: Schema.optional(Schema.Boolean),
});
supportsSkillMentions controls whether the @skill picker is shown. supportsPluginMentions controls whether installed plugins can be mentioned.

​
How to use skills and mentions in a message

1

Open the skill picker

Click the skill icon in the composer toolbar (the wand icon) or type @ to open the mention/skill picker. Start typing to filter by name or description.
2

Select one or more skills

Click a skill to add it to the composer. Selected skills appear as inline chips. You can add multiple skills to a single message.
3

Write your message

Type your prompt as normal. The selected skills will be injected into the provider session automatically when you send.
4

Send

Press Enter or click Send. Synara attaches the ProviderSkillReference list to the turn and the skills are either passed natively to the provider or inlined into the prompt, depending on what the provider supports.

​
Related

Build docs developers (and LLMs) love

Get started for freeTalk to us