Managing Instructions

What are Instruction Files?

An instruction file is a Markdown-formatted text file containing operational guidelines and standards for AI Agents. When creating a new task, Sink automatically reads and injects instruction file content to help Agents understand your workflow, project standards, and expected behavior.

Common uses for instruction files include:

• Defining code style and naming conventions
• Explaining project architecture and core concepts
• Specifying how to use particular tools or libraries
• Listing disabled or restricted operations
• Providing project-specific AI Agent workflows

Instruction File Locations

Sink supports instruction files at two levels:

User-Level Instruction File

A global instruction file that applies to all workspaces. Location:

~/.sink/SINK.md

Workspace-Level Instruction File

An instruction file for a specific workspace with higher priority. Location:

<workspace>/.sink/SINK.md

If both files exist, content is merged in the following order:

1. Workspace-level content (highest priority)
2. User-level content (secondary)
3. Builtin-level content (lowest priority; pre-configured in the distribution)

Creating and Editing Instruction Files

Edit with a Text Editor

Use your preferred text editor to directly edit instruction files:

# Edit user-level instruction file (global)
nano ~/.sink/SINK.md

# Edit workspace-level instruction file (project-specific)
cd /path/to/workspace
nano .sink/SINK.md

After saving, newly created tasks will automatically use the updated instructions.

View Instruction Files in Web UI

View the merged instruction file in the Web UI:

1. Open the Web UI
2. Click “Instructions” in the left menu
3. You can view:
   • Effective view: The final merged instructions (workspace + user)
   • Workspace view: Workspace-level content only
   • User view: User-level content only

The source path of each layer is also displayed in the UI.

Instruction File Best Practices

Content Structure

It’s recommended to organize instruction files into clear sections:

# Project Guidelines

## Overview

Project name, objectives, and core concept descriptions.

## Code Standards

- Programming language and version requirements
- Code style (indentation, naming conventions, etc.)
- Essential best practices to follow

## Architecture

- Project directory structure
- Core module descriptions
- Dependencies and data flow

## Tools and Libraries

- Key dependencies and their versions
- How to configure related tools
- Recommended plugins or extensions

## Workflow

- How to create new features
- How to run tests
- Pre-commit checklist

## Restrictions and Prohibitions

- Files or directories that cannot be modified
- Banned dependencies or practices
- Security-related restrictions

Length Control

• Keep instruction files under 10,000 characters
• Overly long instructions may reduce Agent processing efficiency
• Prioritize the most critical information; details can be added as code comments

Clarity and Specificity

Use clear language and concrete examples:

Good example:

Use TypeScript for development. Must install type definitions (@types/*).
Never use any type unless specifically justified.

Poor example:

Follow best practices. Do the reasonable thing.

Update Frequency

• Regularly update instruction files to keep them in sync with project state
• Update immediately after adding new standards or restrictions
• Remove outdated information

Troubleshooting

Issue: Instruction file is not loaded by the Agent

Solution:

• Confirm the file exists at the correct location: ~/.sink/SINK.md or <workspace>/.sink/SINK.md
• Check that the filename is exactly correct: SINK.md (case-sensitive)
• Ensure the file is pure Markdown format (no YAML frontmatter)
• Newly created tasks use the latest instructions; existing tasks are not affected

Issue: Already created tasks don’t update after modifying instruction file

Solution:

• Instruction files only apply to newly created tasks
• Existing tasks have fixed instructions that won’t change if modified
• To apply new instructions, create a new task

Issue: Multiple instruction files conflict or have duplicate content

Solution:

• Check if both user-level and workspace-level instructions are defined
• Use the Web UI’s “Effective” tab to view the final merged result
• Consider moving common instructions to user-level and project-specific ones to workspace-level

Next Steps

After configuring instruction files, you can:

1. Managing Profiles — Define Agent personality and capabilities
2. Quick Start — Create your first task and observe Agent behavior