Customizing Agents

Why customize

An agent in OpenSail is a tesslate-agent instance plus a system prompt, a bound skill catalog, a bound MCP connector set, a model preference, and an approval policy. Customization is how you turn a generic coding agent into a specialist: a Tailwind UI builder, a FastAPI API author, a security reviewer, a product-ops bot that lives in Slack.

Encode standards

Lock in coding conventions, frameworks, and patterns once, reuse forever

Scope capabilities

Restrict tools, skills, and MCP connectors so the agent does one thing well

Ship it

Publish to your team or the public marketplace as an immutable agent version

Keep control

Approval policies travel with the agent, so dangerous actions still gate the same way

The five levers

System prompt
Bound skills
Bound MCP connectors
Model preference
Approval policy

The character sheet for the agent: role, tone, rules, tech stack, and anti-patterns. System prompts support runtime markers like {mode_instructions}, {project_name}, and {git_branch} that are substituted before each model call.

Skills are reusable markdown capabilities (a code-review checklist, a research methodology, a report template). You attach skills to an agent via the Library. The agent sees the catalog at session start and loads full bodies on demand. See /guides/skills.

Model Context Protocol connectors expose third-party tools (Slack, Gmail, Linear, GitHub) to the agent. You install a connector on your account, attach it to the agent, and its tools get bridged into the agent’s registry at runtime. See /guides/connectors-mcp.

The LiteLLM-routed model used for each session. Pick Anthropic, OpenAI, DeepSeek, Qwen, Google, or any other supported provider. Users can override at runtime if the agent allows it. See /guides/model-management.

Creating an agent

Fork an existing one

The fastest path. You start with a working system prompt and adjust.

Find a base

Open the Marketplace or the Library and find an agent close to what you want.

Fork

Click Fork. A copy lands in your Library with your ownership.

Edit the prompt

Rewrite the system prompt to match your conventions. Keep {mode_instructions} somewhere in the prompt so edit-mode behavior stays consistent.

Attach skills and MCPs

Go to the agent’s detail page. Add skills from the Library tab. Add MCP connectors from the MCP tab.

Pick a model

Set a default model. Choose something faster for quick iteration, something stronger for reasoning-heavy tasks.

Test

Open a test project, run the agent against a representative task, and iterate on the prompt.

Create from scratch

Open the Library

Library then the Agents tab. Click Create New Agent.

Name and metadata

Give it a slug, a display name, an icon, a category, and a short description. These power marketplace search.

System prompt

Write the prompt. Keep it focused: one role, one stack, one set of rules.

Skills

Attach the skills this agent needs. Leave off anything speculative: skills are lazy-loaded and only cost context window on use.

MCP connectors

Attach the connectors this agent must have. Connectors are per-user, so installers attach their own credentials after install.

Model and policy

Set the default model and the default approval policy.

Save and test

Save. Open a project and run through real tasks.

Writing system prompts

A good system prompt has five sections: role, guidelines, stack, constraints, runtime markers.

Role

One line. Who the agent is and what it does.

You are an expert TypeScript and React developer. You build accessible, responsive components using Tailwind and React Hook Form.

Guidelines

How the agent should work.

Always:
- Read the target file before editing
- Use named exports
- Type every prop and return value
- Follow the patterns already in the project

Stack

Preferred libraries.

Stack:
- React 18+ with TypeScript strict mode
- Tailwind CSS, no CSS-in-JS
- React Hook Form + Zod
- React Query for server state

Constraints

What to avoid.

Avoid:
- Class components
- Default exports
- Hardcoded colors outside the Tailwind palette
- Monolithic components; split above 200 lines

Runtime markers

Dynamic context injected at each call.

{mode_instructions}

Project: {project_name}
Branch: {git_branch}
Available tools: {tool_list}

Common markers

Marker	Substituted with
`{mode_instructions}`	Full text for the current edit mode (allow, ask, plan)
`{mode}`	The mode name only
`{project_name}`	Current project display name
`{project_description}`	Project description
`{project_path}`	Workspace path inside the container
`{git_branch}`	Current branch
`{tool_list}`	Comma-separated tool names available this session
`{user_name}`	The signed-in user’s display name
`{timestamp}`	ISO timestamp at call time

Always keep {mode_instructions} in your prompt. It guarantees the agent still honors Plan Mode and Ask Before Edit even if your other instructions conflict.

Binding skills

Skills are the unit of portable know-how in OpenSail. Each skill is a markdown document with a name, a short description, and a body. The agent only sees the name and description at session start. When it decides it needs one, it calls load_skill and the full body is injected into the turn. Three sources feed the catalog:

Built-in skills shipped with the platform (for example, project-architecture). Available to every agent.
Skills you installed on this agent via the Library. You attach them explicitly.
Project-file skills discovered at .agents/skills/SKILL.md in the workspace. Any agent working in that project sees them.

For authoring skills, see /guides/skills.

Binding MCP connectors

MCP (Model Context Protocol) is how OpenSail bridges third-party tool servers into the agent’s tool registry. You install a connector once on your account (with your credentials, encrypted at rest), then attach it to any agent. When the agent starts a session, the worker:

Looks up every AgentMcpAssignment for the agent
Loads the user’s UserMcpConfig for each (with credentials)
Connects to each MCP server over streamable HTTP
Bridges the server’s tools, resources, and prompts into the agent’s ToolRegistry

From the agent’s perspective, connector tools look identical to built-in tools. They get used the same way. For connector setup and credential management, see /guides/connectors-mcp.

Approval policy

Every agent carries a default edit mode. Users can override per session, but your default matters because it sets the expected behavior.

Default	When to pick it
Ask Before Edit	Any agent that writes files or runs shell commands. Safest default.
Allow All Edits	Agents meant for trusted contexts (personal projects, sandboxed environments).
Plan Mode	Agents that should only plan and never execute. Useful for review agents, security scanners, architects.

Publishing to the marketplace

Polish

Clear system prompt, representative test runs, working skill and MCP bindings.

Describe

Fill in the marketplace description, category, and tags. Add example prompts that show the agent at its best.

Choose visibility

Private (just you), team-only, or public. Public listings go through the approval pipeline.

Set pricing

Free, one-time purchase, subscription, or API-metered. Creator payouts pay 90% to you, 10% to the platform. See /guides/billing.

Submit

Submit for review. The approval pipeline runs automated security and manifest checks, then a sandbox evaluation, then a human review.

Iterate

Publish updates as new immutable versions. Installers can pin, auto-update, or manually update per their policy.

Public marketplace agents are visible to everyone. Do not hardcode secrets or environment-specific paths into system prompts. Use runtime markers for project-specific context.

The MarketplaceAgent model

Agents are stored as MarketplaceAgent rows with item_type="agent". The relevant columns for customization:

Field	Purpose
`slug`	Stable identifier
`name`, `description`, `icon`, `category`, `tags`	Marketplace metadata
`system_prompt`	The prompt body (markdown with runtime markers)
`tools`	Optional allowlist of tool names; null means all available tools
`model`	Default LiteLLM model id
`approval_mode`	Default edit mode
`visibility`	Private, team, or public
`price`	Free, one-time, subscription, or API-metered
`forkable`	Whether installers can fork the agent
`is_builtin`	Reserved for platform-shipped agents; not user-writable

Attachments live in adjacent tables:

AgentSkillAssignment binds a skill to an agent
AgentMcpAssignment binds an installed MCP server to an agent

Testing your agent

Use a test project

Make a dedicated workspace. Clone a typical project you’d use this agent on.

Run representative tasks

Not just “hello world”. Run the actual tasks users will throw at this agent.

Review every tool call

Put the agent in Ask Before Edit. Review what it wants to do. Note where it picks the wrong tool or the wrong file.

Check for drift

Does it follow your guidelines or ignore them under pressure? Add explicit rules for the failure modes.

Stress-test the model

Long-horizon tasks reveal whether your prompt holds up. Run multi-step workflows and watch for off-pattern code.

Best practices

One specialty per agent

Focused agents outperform generalists. “React + Tailwind UI specialist” beats “full-stack developer” on UI tasks and vice versa.

Iterate the prompt

Every time the agent does something wrong, add a rule that prevents it. Every time it does something right, generalize it into the prompt. Prompts are versioned like code.

Narrow tool access where you can

A review agent does not need bash_exec. A docs writer does not need multi_edit. Narrow tools reduce drift and lower risk.

Include examples

LLMs follow examples better than abstractions. Include a short code snippet in your system prompt showing the pattern you want.

Default to Ask Before Edit

Ship new agents in Ask Before Edit. Let users opt into Allow All once they trust the behavior.

Next steps

Using Agents

The user-side guide to running agents in chat

Skills

Author and publish reusable agent skills

Connectors (MCP)

Wire external tools into any agent

Model Management

Choose models, BYOK, or self-host

Get Started

Install and Run

Core Concepts

Working with Projects

Agents and Skills

Ship and Share

Self-Hosting

Developer Guide

Customizing Agents

Why customize

Encode standards

Scope capabilities

Ship it

Keep control

The five levers

Creating an agent

Fork an existing one

Create from scratch

Writing system prompts

Common markers

Binding skills

Binding MCP connectors

Approval policy

Publishing to the marketplace

The MarketplaceAgent model

Testing your agent

Best practices

Next steps

Using Agents

Skills

Connectors (MCP)

Model Management

​Why customize

Encode standards

Scope capabilities

Ship it

Keep control

​The five levers

​Creating an agent

​Fork an existing one

​Create from scratch

​Writing system prompts

​Common markers

​Binding skills

​Binding MCP connectors

​Approval policy

​Publishing to the marketplace

​The MarketplaceAgent model

​Testing your agent

​Best practices

​Next steps

Using Agents

Skills

Connectors (MCP)

Model Management

Why customize

The five levers

Creating an agent

Fork an existing one

Create from scratch

Writing system prompts

Common markers

Binding skills

Binding MCP connectors

Approval policy

Publishing to the marketplace

The MarketplaceAgent model

Testing your agent

Best practices

Next steps