Getting started
Replit is a cloud development environment capable of writing and running any framework or stack. To build a custom template, there are two recommended paths:
- Import from a Git provider — Import your existing starter stack (or one matching your preferences) from GitHub, GitLab, or Bitbucket.
- Fork the Blank template — Fork the Blank template to start from scratch with a completely empty development environment.
Customers have successfully built templates matching Rust, Python, Java, C++, and many other stacks — if it runs at all, it can run on Replit.
We recommend working with Replit’s Field Engineering team when building your first templates. They have extensive experience setting up custom templates across a wide range of stacks and are available to help. Reach out to your Account Executive to get connected.
Custom templates are available exclusively on the Enterprise plan. Only org admins can pin and manage templates.
How custom templates work
A custom template is a standard Replit App in your organization that has been pinned to the Agent input box. When a builder selects it:
- Agent creates a new app by forking the template (all files are copied)
- Agent skips the planning phase and goes straight to building
- The template’s
custom_instruction/instructions.md file is injected into Agent’s context
- Custom skills from
.agents/skills/ are discovered and made available
- The
replit.md file provides ongoing project context
This means your organization’s standards, patterns, and tooling are baked in from the very first interaction.
Template file structure
Here is the recommended layout for a custom template:
my-template/
├── .replit # App configuration (run commands, ports, modules)
├── replit.md # Agent memory: project overview and preferences
├── custom_instruction/
│ └── instructions.md # Company instructions injected into Agent's prompt
├── .agents/
│ └── skills/
│ └── my-skill/
│ └── SKILL.md # Custom skills Agent can invoke on demand
└── ... # The rest of your repo structure
Set up a custom template
Create the base app
Create a new Replit App in your organization. Set up the project with all the files, dependencies, and configuration your builders need as a starting point. This includes:
- Source code scaffolding (components, utilities, config files)
- Pre-installed dependencies (
package.json, requirements.txt, etc.)
- Environment configuration in the
.replit file
If your template relies on API keys, tokens, or other credentials, add them to the template’s Secrets (under the Tools pane) before pinning. When a builder creates a new app from the template, all secrets are copied into the new app automatically, so builders can start working without configuring credentials themselves.
Document every secret in custom_instruction/instructions.md (or in a dedicated skill) so builders know what is available and what each key is used for.
Secrets are copied at fork time, not dynamically synced. If you rotate a key or add a new secret to the template, existing apps that were previously forked are not updated. Builders must add or update secrets manually in those apps.
Write custom instructions
Create a file at custom_instruction/instructions.md in the project root. This is the most important file in your template — it tells Agent how your organization builds software.
The folder name must be custom_instruction (singular), not custom_instructions.
- Architecture patterns: How your apps should be structured
- Coding standards: Naming conventions, file organization rules, linting expectations
- Component usage: Which libraries and components to use (and which to avoid)
- API patterns: How to call your backend services, handle authentication, manage errors
- Testing requirements: What tests are expected and how to run them
- Deployment guidelines: Environment-specific configuration and deploy workflows
# Company Engineering Standards
## Architecture
All web applications use React with TypeScript. Use functional components
with hooks exclusively. State management uses Zustand for local state
and React Query for server state.
## Component Library
Use our internal design system package `@acme/ui`. Never use raw HTML
elements for buttons, inputs, forms, or modals — always use the
corresponding component from `@acme/ui`.
Import components like this:
```tsx
import { Button, TextField, Modal } from '@acme/ui';
```
## API Integration
All API calls go through the `@acme/api-client` package. Never use
raw fetch or axios directly. Authentication is handled automatically
by the client.
## Testing
Every component must have a corresponding test file. Use Vitest
for unit tests and Playwright for integration tests.
.agents/skills/ rather than keeping everything in instructions.md. Skills are loaded on demand when relevant, so they do not count against the instruction size limit and keep your main instructions focused on high-level rules.
Add custom skills
Create skills in the .agents/skills/ directory for specialized workflows that Agent should follow. Each skill is a directory containing a SKILL.md file with YAML frontmatter.
.agents/skills/
├── use-design-system/
│ └── SKILL.md
├── api-integration/
│ └── SKILL.md
└── run-tests/
└── SKILL.md
SKILL.md needs a name and description in its frontmatter:
---
name: use-design-system
description: Use when building UI components. Provides component patterns, theming rules, and accessibility requirements for the Acme design system.
---
# Acme Design System
## Available components
- `Button` — Primary, secondary, and ghost variants
- `TextField` — Text input with validation support
- `Modal` — Dialog overlay with focus trapping
...
| Field | Required | Details |
|---|
name | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. |
description | Yes | Max 1,024 characters. Describes what the skill does and when to use it. |
enabled | No | Defaults to true. Set to false to disable without deleting. |
name and description in its prompt. It reads the full SKILL.md content on demand when the skill is relevant to the current task. This means the description is critical — write it to match the scenarios where Agent should use the skill.
Skills can also include supporting files alongside SKILL.md:
.agents/skills/use-design-system/
├── SKILL.md
├── references/
│ └── component-api.md
└── assets/
└── theme-tokens.json
replit.md in the project root with your template’s architecture overview. This file is always loaded into Agent’s context and serves as ongoing project memory.
The file should have these four sections:
# Overview
Task management application built with React, TypeScript, and the Acme
design system. Uses Express.js backend with PostgreSQL.
# User Preferences
- Use TypeScript for all files
- Prefer functional components with hooks
- Follow Acme coding standards
# System Architecture
- Frontend: React + TypeScript + @acme/ui
- Backend: Express.js + TypeScript
- Database: PostgreSQL with Drizzle ORM
- Auth: Acme SSO via @acme/auth
# External Dependencies
- @acme/ui: Internal design system
- @acme/api-client: API integration layer
- @acme/auth: Authentication SDK
replit.md as the project evolves. If the file grows beyond approximately 4,000 tokens, Agent automatically summarizes it to keep it focused and useful.
For more details, see replit.md.
Pin the template to your organization
Once your template is ready:
- Navigate to the template app in your organization
- Open the app’s action menu (three-dot menu)
- Select Pin to Agent input box
Only org admins (members of the system_admins role) can pin and unpin templates.
The template now appears as a selectable pill below the Agent input box for every member of your organization. To remove it, open the same menu and select Unpin from Agent input box.
Control template access
Pinning makes a template visible to every org member. For more targeted distribution, use the Invite button on the template app to share it with specific Groups or individual users. This lets you limit which teams or people can see and fork the template while keeping it unpinned from the org-wide input box.
What happens when a builder selects a template
When an org member picks a pinned template from the Agent input box:
- Fork: A new app is created as a copy of the template, with all files included
- Skip planning: Agent bypasses the initial planning conversation and goes directly into building mode
- Load instructions:
custom_instruction/instructions.md is read and injected into Agent’s system prompt as company-provided guidance
- Discover skills: Skills in
.agents/skills/ are identified and listed in Agent’s context for on-demand loading
- Load project context:
replit.md is read and injected into Agent’s context (or auto-generated if missing)
- Inherit configuration: The
.replit file, dependencies, and all template files carry over to the new app
The builder can immediately start prompting Agent with their specific requirements, and Agent operates within the guardrails established by the template.
How files work together
Each configuration file serves a distinct role:
| File | Purpose | When Agent reads it | Mutable by Agent |
|---|
custom_instruction/instructions.md | Organization standards and rules | Always (injected into system prompt) | No |
.agents/skills/*/SKILL.md | Specialized workflows and patterns | On demand (when relevant) | Yes (Agent can create skills too) |
replit.md | Project overview and preferences | Always (injected into system prompt) | Yes (Agent updates it over time) |
.replit | Runtime configuration | When configuring the app | Yes |
custom_instruction/instructions.md is your static, authoritative source for organizational standards. replit.md is the living document that Agent maintains as the project evolves. Skills are on-demand reference material for specific workflows.
Best practices
Keep instructions focused
Write custom_instruction/instructions.md for the patterns that matter most. Focus on:
- Decisions that are hard to reverse (architecture, data models)
- Patterns that must be consistent (component usage, API conventions)
- Standards the builder might not know about (internal libraries, team conventions)
Avoid including changelogs, implementation details, or information that changes frequently.
Write discoverable skill descriptions
The description field in SKILL.md frontmatter is what Agent uses to decide when to load a skill. Write descriptions that match the tasks where the skill is relevant:
# Good — describes when to use it
description: Use when building forms or handling user input. Provides validation patterns, error display conventions, and accessible form layouts.
# Less effective — too vague
description: Form utilities and helpers.
Organize skills by workflow
Group skills around workflows rather than technical categories:
| Approach | Example |
|---|
| By workflow | build-a-form, connect-to-api, add-auth |
| By technical area | react-utils, api-helpers, auth-config |
Iterate on your template
Templates improve with use. After your team starts building with a template:
- Watch for patterns Agent gets wrong and add them to
instructions.md
- Create new skills when Agent solves a problem well — capture the solution
- Update base dependencies and configurations as your stack evolves
- Test changes by creating a new app from the template to verify the experience
Template updates and existing apps
Changes to the template app are reflected in new apps created from it. Existing apps that were previously forked from the template are independent copies and do not receive updates.
