How to Set Up Custom Patterns in Fabric: Complete Configuration Guide

Run fabric --setup to configure a custom patterns directory, then create subfolders containing a system.md file to extend Fabric with private, update-safe prompts that take precedence over built-in patterns.

Fabric treats a pattern as a reusable prompt package comprising system, user, and optional configuration files. While the tool ships with a built-in collection stored in data/patterns, you can create a custom patterns directory to store private prompts that persist across application updates. Setting up custom patterns in Fabric involves configuring a directory path via the interactive setup or environment variables, then populating it with standard Fabric pattern structures.

How Custom Patterns Work in Fabric

Fabric’s architecture uses three core components to enable custom pattern support without modifying the core codebase.

The CustomPatterns Plugin

Located in internal/tools/custom_patterns/custom_patterns.go, the CustomPatterns plugin registers an interactive setup question that prompts for your custom directory path. It automatically expands the ~ character to your home directory, resolves the absolute path, and creates the folder if it does not exist. The plugin exposes an IsConfigured() method that checks whether a valid custom directory has been set.

The PatternsLoader

The PatternsLoader in internal/tools/patterns_loader.go handles the actual pattern discovery. When loading patterns, it always scans the built-in folder (o.Patterns.Dir) and the path stored in CustomPatterns.CustomPatternsDir. It merges both sets into a unified map, adding custom entries after built-in ones. This merge order ensures that custom patterns take precedence when names collide.

The PluginRegistry

The PluginRegistry in internal/core/plugin_registry.go wires the CustomPatterns plugin into the global registry. This integration ensures the plugin participates in the interactive fabric --setup flow and writes its configuration values into the generated .env file.

Step-by-Step: Configure Your Custom Patterns Directory

Run the Interactive Setup

Execute the setup command and select the Custom Patterns option:

fabric --setup

When prompted, enter an absolute or relative path (e.g., ~/my-custom-patterns). Fabric expands the tilde to your home directory, resolves the full absolute path, and creates the directory if it is missing. This path is then written to your .env configuration file.

Verify the Configuration

After setup, your .env file contains the CUSTOM_PATTERNS_DIRECTORY variable (derived from the plugin's EnvNamePrefix). The CustomPatterns.IsConfigured() method returns true when this variable points to a valid directory, signaling the PatternsLoader to include it in subsequent scans.

Creating Custom Pattern Files

Once the directory is configured, populate it with pattern folders following the same structure as built-in patterns.

Required and Optional Files

Each subfolder inside your custom directory represents a single pattern identified by its folder name:

• Required: system.md — Contains the system prompt instructions.
• Optional: user.md — Contains default user prompt content.
• Optional: config.json — Contains pattern-specific configuration parameters.

Example Pattern Creation

Create a custom pattern named my-analyzer:

mkdir -p ~/my-custom-patterns/my-analyzer

cat > ~/my-custom-patterns/my-analyzer/system.md <<'EOF'
You are an expert security analyst. Provide concise, factual answers focusing on vulnerabilities and mitigation strategies.
EOF

cat > ~/my-custom-patterns/my-analyzer/user.md <<'EOF'
Analyze the following input for security risks:
EOF

Invoke the pattern using the standard flag:

fabric --pattern my-analyzer "Open ports 22, 80, and 443 detected on the server"

Pattern Resolution and Precedence

Runtime Merging Behavior

When you execute fabric --listpatterns, the loader displays both built-in and custom pattern names. During execution, the loader in internal/tools/patterns_loader.go populates the pattern map in two phases:

1. Built-in patterns are loaded from the default data/patterns directory.
2. Custom patterns are loaded from CustomPatterns.CustomPatternsDir and added to the same map.

Because custom entries are added after built-in ones, custom patterns automatically override built-in patterns when sharing the same identifier. This precedence mechanism ensures your private definitions always take priority without deleting or modifying the original built-in files.

Environment Variable Configuration

Instead of using interactive setup, you can manually define the directory in your .env file:

CUSTOM_PATTERNS_DIRECTORY=/home/user/fabric-patterns

Fabric reads this variable on startup. The PatternsLoader merges this directory automatically whenever IsConfigured() returns true, ensuring your custom prompts persist across application upgrades.

Summary

• Custom patterns in Fabric are stored in a user-defined directory separate from the built-in data/patterns collection to prevent update overwrites.
• Configure the directory via fabric --setup or by setting the CUSTOM_PATTERNS_DIRECTORY environment variable in your .env file.
• The CustomPatterns plugin (internal/tools/custom_patterns/custom_patterns.go) handles path resolution and directory creation.
• The PatternsLoader (internal/tools/patterns_loader.go) merges built-in and custom directories, with custom patterns taking precedence due to later insertion into the pattern map.
• Each pattern requires at least a system.md file inside a named subfolder; optional user.md and config.json files follow the same conventions as built-in patterns.

Frequently Asked Questions

Where does Fabric store the custom patterns directory configuration?

Fabric stores the path in your .env file using the variable CUSTOM_PATTERNS_DIRECTORY. The CustomPatterns plugin writes this value during interactive setup (fabric --setup) and the PluginRegistry ensures it persists across sessions.

What happens if a custom pattern has the same name as a built-in pattern?

The custom pattern takes precedence. In internal/tools/patterns_loader.go, the loader adds custom patterns to the map after built-in patterns. When duplicate keys exist, the later entry (your custom version) overwrites the earlier one, ensuring your private definitions are always used.

Can I use environment variables instead of running fabric --setup?

Yes. Manually add CUSTOM_PATTERNS_DIRECTORY=/path/to/folder to your .env file. The PatternsLoader checks IsConfigured() from the CustomPatterns plugin; if the directory exists and is readable, Fabric automatically merges it with the built-in pattern set without requiring interactive setup.

What files are required to create a valid custom pattern?

You must include a system.md file inside a subfolder of your custom patterns directory. The subfolder name becomes the pattern identifier. Optional files include user.md for default user prompts and config.json for pattern-specific settings, mirroring the structure found in the built-in data/patterns directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}