Install Buffaly and call your first action.

Before you start

Start with Buffaly as an installed local application. The packaged installer is the normal quickstart path; you can inspect or customize the source later if you need to extend the runtime.

You do not need Visual Studio for this guide. If you later want to compile your own DLL, you can use your normal .NET build process, CI pipeline, or another editor.

1. Install Buffaly

Download the latest Buffaly Windows installer and run it. The installer should set up the local runtime, app files, and launch shortcuts so you can start from the Start Menu instead of building from source.

Use the stable installer link unless you have been given a specific release build. You only need a source checkout when you are contributing to Buffaly or building custom runtime components.

2. Connect OpenAI

Before Buffaly can run model-backed agent tasks, configure OpenAI through Buffaly's OpenAI settings. Do this before creating skills or testing actions.

Do not set OpenAI credentials through environment variables for the default Buffaly Web install. Use the OpenAI settings screen so Buffaly can store the selected ChatGPT/Codex account or API key in its local settings store.

3. Run a first task

Start with a plain prompt before customizing anything. This confirms that Buffaly is installed, the local runtime is available, and OpenAI authentication works.

Summarize what Buffaly can do in three bullets.

4. Know where your files live

Buffaly projects are file-backed. You can inspect the files that define prompts, skills, ProtoScript actions, and imported DLLs.

Project.pts
Prompts/
  master.md
ContextPrompts/
  Coding.prompt.md
Skills/
  MySkill/
    PromptActions.pts
    Prompts/
      MyPrompt.prompt.md
    lib/
      MyCompany.Tools.dll

• Project.pts is the project entry point.
• Prompts/ contains project-level prompt files.
• ContextPrompts/ contains optional behavior overlays.
• Skills/<SkillName>/Prompts/ contains prompt-only skill instructions.
• Skills/<SkillName>/PromptActions.pts registers prompt actions or skill actions.
• Skills/<SkillName>/lib/ contains DLLs imported for that skill.

5. Create a prompt-only skill

A prompt skill is the simplest Buffaly customization. It is similar to skills in other agents: a named instruction that teaches Buffaly how to do a repeatable task.

Remember how to write release notes for this project.
Use these sections: Added, Changed, Fixed, Risks, and Next Steps.
Keep it concise and focused on what changed.

Skills/ReleaseNotes/PromptActions.pts
Skills/ReleaseNotes/Prompts/WriteReleaseNotes.prompt.md

The exact folder and file names may vary based on the skill name Buffaly chooses. The important thing is that prompt instructions are durable files you can review and edit.

6. Create a small ProtoScript action

Once a prompt skill is not enough, create a typed action. A typed action has a name, inputs, and executable behavior. This is how Buffaly moves from instructions into software behavior.

A simple action might estimate shipping from a package weight:

[SemanticProgram.InfinitivePhrase("to calculate a shipping estimate")]
prototype ToCalculateShippingEstimate : PromptAction
{
    Description = @"weightPounds - package weight in pounds.";

    function Execute(decimal weightPounds) : string
    {
        decimal estimate = 5.00 + (weightPounds * 1.25);
        return "Estimated shipping: $" + estimate;
    }
}

Then ask Buffaly:

Estimate shipping for a 10 pound package.

In a packaged install, prefer the built-in skill/action authoring UI or authoring command when available. Direct file editing is useful for learning, but Buffaly's typed authoring tools can validate and place action definitions more safely.

7. Import a DLL and call your own code

The most important customization path is calling code you already have. Buffaly can import a DLL into a skill folder, add references/imports, and expose a typed wrapper action.

Suppose your existing DLL contains this C# code:

namespace MyCompany.Tools;

public static class OrderLookup
{
    public static string GetOrderStatus(string orderId)
    {
        return "Order " + orderId + " is ready.";
    }
}

Import the DLL into a skill-local library folder:

Skills/Orders/lib/MyCompany.Tools.dll

The target ProtoScript file should include a DLL reference and import similar to:

reference "lib/MyCompany.Tools.dll" MyCompany.Tools;
import MyCompany.Tools MyCompany.Tools.OrderLookup OrderLookup;

Then expose a wrapper action:

[SemanticProgram.InfinitivePhrase("to get order status")]
prototype ToGetOrderStatus : PromptAction
{
    Description = @"orderId - order identifier.";

    function Execute(string orderId) : string
    {
        return OrderLookup.GetOrderStatus(orderId);
    }
}

Test it with:

What is the status of order 12345?

If the action cannot load, check that the DLL and any sibling dependencies are present in the skill lib folder, and confirm the namespace/type name in the import line.

Troubleshooting