Buffaly Logo
How-to

Add a ProtoScript skill

Create Buffaly-native actions with typed parameters, executable logic, semantic discovery, and validation without starting in C#.

ProtoScript is for technical Buffaly users and extenders who need more structure than a text prompt, but do not yet need a compiled DLL or full service boundary.

Quick answer

A ProtoScript skill is a discoverable capability area made from .pts files. A skill defines an action root such as FileSystemSkillAction, a skill entity such as FileSystemSkill, and action prototypes such as ToReadTextFile.

Each action usually has SemanticProgram.InfinitivePhrase annotations, a To... prototype name, a clear Description, typed Execute parameters, and a return value or summary the Buffaly agent can use.

Example prompt

Create or check a ProtoScript action for validating a wiki article path. Use the active project Skills layout. Put the action in the right skill if one exists. Use strong semantic phrases, a clear description, typed parameters, and a concise result. Compile or validate the project, reload if needed, and test that discovery can find the action by phrase.

When to choose ProtoScript

ProtoScript is a middle layer: more structured than markdown or a prompt action, lighter than compiled code, and discoverable through action and entity search.

Need Better fit
Stable text or checklist workflow. Prompt skill or prompt action.
Typed parameters, validation, or executable project logic. ProtoScript action.
Deterministic SDK, protocol, or file behavior that should be compiled and tested. C# DLL-backed tool or wrapper.
Lifecycle, identity, state, config, or multiple methods. Service.
Configured external MCP server. MCP-backed service instance.
Durable fact, preference, account, or environment. Ontology memory.

Where .pts files live

ProtoScript skills live under the active source tree project. Treat the paths below as implementation examples, then verify the active checkout path before editing older docs paths or copied examples.

Core project files

  • Project.pts entry point.
  • Core/CoreOntology.pts base prototypes.
  • Core/CoreActions.pts discovery actions.

Skill locations

  • Skills/<SkillName>/index.pts common skill/action location.
  • Web-module skill mirrors may exist when a web module exposes related actions.

Anatomy of a ProtoScript skill

Action root

Groups related actions under a shared base action type, such as FileSystemSkillAction. Use the skill action root instead of inheriting from the broadest core action by default.

Skill entity

Gives the skill a discoverable entity, such as FileSystemSkill, and points ActionRoot at the base action type so Buffaly can enumerate actions.

Skill entity: FileSystemSkill
Action root: FileSystemSkillAction
Actions: ToReadTextFile, ToWriteTextFile, ToValidateWikiArticlePath

Anatomy of a ProtoScript action

A good action is easy for semantic discovery to find, safe to call, and clear in its result. Keep implementation logic small and delegate to trusted C# tools or services when the behavior needs mature validation.

  • Infinitive phrases that describe how users ask for it.
  • A To... prototype name.
  • Inheritance from the skill action root.
  • Optional context markers such as CodingContext.
  • A clear description.
  • A typed Execute signature and concise return value.
@SemanticProgram.InfinitivePhrase("to validate a wiki article path")
prototype ToValidateWikiArticlePath extends FileSystemSkillAction
	Description = "Validate that a wiki article path is under the configured wiki root."
	Execute(path: Text, wikiRoot: Text) => WikiPathValidationResult

How discovery works

Buffaly can search candidate actions and entities, list skills, enumerate skill actions, load a ProtoScript action tool, and inspect loaded ProtoScript action tools. That is why action phrases and descriptions matter.

Discovery actions

ToSearchCandidateActions, ToSearchCandidateEntities, ToListSkills, ToListSkillActions, ToLoadProtoScriptActionTool, and ToListLoadedProtoScriptActionTools support discovery and loading.

User-facing rule

Users should ask for the outcome, not memorize prototype names. Strong phrases help Buffaly bind normal language to the right action.

Weak phrase Better phrase
to check stuff to validate a markdown article under the wiki root
to handle files to read a UTF-8 text file by absolute path
to make report to create a wiki quality report for a documentation folder

Easiest way: ask Buffaly to create it

Because ProtoScript participates in the ontology, the most reliable path for many users is to describe the desired action and ask Buffaly to create or update it in the correct node, validate it, and prove discovery can find it.

Add to existing skill

Add an action to the FileSystem skill that validates markdown files under the wiki root. Use typed parameters, strong semantic phrases, compile, reload if needed, and test discovery.

Create a new skill

Create a wiki quality check skill with actions for checking article path, title, links, and front matter. Reuse existing services where possible and return a concise validation summary.

Improve an action

Find the existing action with a vague phrase or missing description. Improve only the semantic phrases and description, then validate discovery ranking.

Validation prompt

Show the active project path, changed .pts files, compile result, discovery result, loaded tool result, smoke test output, and whether a runtime reload or new session was required.

Manual path

  1. Choose the boundary: prompt action, ProtoScript action, C# tool, service, MCP service, or memory.
  2. Find the active project root and verify it is the checkout Buffaly is actually using.
  3. Use an existing skill when possible. Create a new skill only when the capability area is genuinely new.
  4. Add the action with semantic phrases, To... prototype name, description, typed Execute signature, and a clear result.
  5. Prefer ProtoScriptAuthoringService upsert and semantic phrase tools when they are available instead of direct file edits.
  6. Compile or validate, reload if needed, then test discovery and execution.

Validate, compile, and reload

Runtime may need a reload, reset, or new session after a ProtoScript edit. Treat validation as layers, not a single green check.

File validation

The file exists at the active path and only intended files changed.

Compile validation

The ProtoScript project compiles or reports actionable diagnostics.

Discovery validation

Semantic action and entity search can find the skill by natural phrases.

Skill validation

The skill entity and action root enumerate the new action correctly.

Loading validation

The action loads as a ProtoScript action tool and appears in the loaded tool list.

Smoke validation

A small execution test returns the expected summary or validation result.

Common mistakes and troubleshooting

  • Editing the wrong project path or an older docs copy.
  • Using a prompt action when typed parameters and validation are needed.
  • Using ProtoScript when lifecycle, identity, state, or config belongs in a service.
  • Skipping semantic phrases or writing vague descriptions.
  • Inheriting from a core action by default instead of the skill action root.
  • Directly editing .pts files when authoring tools exist.
  • Forgetting compile, reload, discovery, or smoke validation.
  • Putting secrets in .pts files. Use configured secret storage instead.