create_instruction

Generate VS Code .instructions.md files with custom descriptions and markdown content to document procedures and workflows.

Instructions

Create a new VS Code .instructions.md file with the specified description and content.

Input Schema

TableJSON Schema

Name	Required	Description
`instruction_name`	Yes	The name for the new instruction (with or without extension)
`description`	Yes	A brief description of what this instruction does
`content`	Yes	The main content/instructions in markdown format

Implementation Reference

src/mode_manager_mcp/tools/instruction_tools.py:35-50 (handler)

MCP tool handler function for 'create_instruction'. Checks read-only mode and delegates core logic to InstructionManager.create_instruction, returning success/error messages.

def create_instruction(
    instruction_name: Annotated[str, "The name for the new instruction (with or without extension)"],
    description: Annotated[str, "A brief description of what this instruction does"],
    content: Annotated[str, "The main content/instructions in markdown format"],
) -> str:
    """Create a new VS Code .instructions.md file with the specified description and content."""
    if read_only:
        return "Error: Server is running in read-only mode"
    try:
        success = instruction_manager.create_instruction(instruction_name, description, content)
        if success:
            return f"Successfully created VS Code instruction: {instruction_name}"
        else:
            return f"Failed to create VS Code instruction: {instruction_name}"
    except Exception as e:
        return f"Error creating VS Code instruction '{instruction_name}': {str(e)}"

src/mode_manager_mcp/instruction_manager.py:401-436 (helper)

Core helper method in InstructionManager that implements the file creation logic: ensures extension, checks existence, builds frontmatter with applyTo '**' and description, writes file using write_frontmatter_file.

def create_instruction(self, instruction_name: str, description: str, content: str) -> bool:
    """
    Create a new instruction file.

    Args:
        instruction_name: Name for the new .instructions.md file
        description: Description of the instruction
        content: Instruction content

    Returns:
        True if successful

    Raises:
        FileOperationError: If file cannot be created
    """

    # Ensure filename has correct extension
    instruction_name = self._ensure_instruction_extension(instruction_name)

    file_path = self.prompts_dir / instruction_name

    if file_path.exists():
        raise FileOperationError(f"Instruction file already exists: {instruction_name}")

    # Create frontmatter with applyTo field so instructions are actually applied
    frontmatter: Dict[str, Any] = {"applyTo": "**", "description": description}

    try:
        success = write_frontmatter_file(file_path, frontmatter, content, create_backup=False)
        if success:
            logger.info(f"Created instruction file: {instruction_name}")
        return success

    except Exception as e:
        raise FileOperationError(f"Error creating instruction file {instruction_name}: {e}")

src/mode_manager_mcp/tools/__init__.py:20-20 (registration)
Triggers registration of all instruction tools, including 'create_instruction', via register_instruction_tools() call in register_all_tools().
```
register_instruction_tools()
```

src/mode_manager_mcp/tools/instruction_tools.py:20-30 (schema)

Tool schema definition in @app.tool annotations, specifying parameters (instruction_name, description, content), return type, and hints like non-idempotent and non-readonly.

annotations={
    "idempotentHint": False,
    "readOnlyHint": False,
    "title": "Create Instruction",
    "parameters": {
        "instruction_name": "The name for the new instruction. If .instructions.md extension is not provided, it will be added automatically.",
        "description": "A brief description of what this instruction does. This will be stored in the frontmatter.",
        "content": "The main content/instructions in markdown format.",
    },
    "returns": "Returns a success message if the instruction was created, or an error message if the operation failed.",
},

Mode Manager MCP