Choosing the right boundary keeps the Buffaly agent easier to use, safer to operate, and easier to extend. Older source paths may still say OpsAgent; treat that as legacy/source naming unless you are naming a checked-in path.
Quick answer
Start with the least powerful durable form that still makes the work reliable.
| Need | Prefer | Why |
|---|---|---|
| Durable fact, preference, account, system, or environment | Ontology memory | Helps future semantic entity binding. |
| Procedure still mostly operational knowledge | Workflow memory | Captures steps, risks, validation, and completion criteria. |
| Stable prompt-driven workflow | Prompt action | Trusted instructions can be discovered and run. |
| Typed parameters, validation, or execution | ProtoScript action | One typed action can be discovered and called. |
| SDK, protocol, parsing, or deterministic behavior | Native or DLL-backed wrapper | Compiled/testable code is safer for deterministic work. |
| Identity, lifecycle, state, configuration, or related methods | Service | The service owns the boundary; selected methods can project as flat tools. |
| Related capabilities installed together | Skill | Groups actions, prompts, services, DLLs, and supporting files. |
| One configured MCP server | MCP-backed service instance | Each binding has its own endpoint, auth, and capability boundary. |
| Routes, JsonWs, UI, static assets | Web module | Owns web-facing packaging and startup behavior. |
| Model/provider backend | Provider module | Provider catalog and execution are distinct from ordinary tools. |
Extension boundaries in user terms
Memory and workflow memory
Use memory for knowledge, not behavior. Stable repository roots, accounts, environments, and preferences belong in ontology memory. Reusable but evolving procedures belong in workflow memory. Do not store secrets in normal memory.
Prompt actions
Use for stable instruction-driven work: review, drafting, triage, checklist execution, planning, summarization, or verified documentation workflows.
ProtoScript actions
Use when the Buffaly agent should call a named typed operation with parameters, return values, semantic phrases, validation, or project operations.
Native tools and DLL wrappers
Use compiled code for SDK calls, protocol handling, parsing, file transformation, performance-sensitive behavior, or testable deterministic logic.
Services and MCP bindings
Use services for lifecycle, identity, state, configuration, and related methods. Model MCP as per-binding service instances, not one global bucket.
Skills, web modules, and provider modules
Use skills to group related capabilities, web modules for UI/routes/JsonWs/static assets, and provider modules only for model/provider backends.
Practical promotion path
- Start with a remembered workflow while the procedure is still changing.
- Promote to a prompt action when instructions are stable and repeated.
- Promote to a ProtoScript action when typed parameters, validation, semantic discovery, or execution matter.
- Move deterministic or protocol-heavy behavior into compiled code and expose a thin wrapper.
- Use a service when identity, lifecycle, state, configuration, or related methods matter.
- Group related artifacts into a skill when users and the Buffaly agent should discover them together.
- Package web-facing assets as a web module when UI, routes, JsonWs, or static files are involved.
- Use a provider module only for model/provider backends.
Semantic discovery makes capabilities usable
Buffaly can discover actions and entities by meaning, not only exact names. Use SemanticProgram.InfinitivePhrase(...) for actions and SemanticEntity(...) for names users will say. Skills should expose an ActionRoot, and loaded action tools prove runtime callability.
How to verify a new capability
- Confirm prompt, .pts, service, skill folder, module manifest, or provider module exists at the expected absolute path.
- Confirm installed skill folders have
index.ptsand enabled skills appear inSkills/index.ptswhen appropriate. - Confirm semantic phrases and entity names are present.
- Compile or validate the project after ProtoScript changes.
- Search candidate actions and load the selected action when needed.
- Check service diagnostics or provider catalog evidence when services or providers are involved.
- Verify docs, prompts, commits, and memory do not contain secret values.
- Keep git status scoped and commit only intended files.
Example user requests
Remember first
Remember this verified article improvement workflow. Include source inspection, target-only edits, validation, scoped git status, and commit-hash reporting.
Promote to a prompt action
Turn the article improvement workflow into a prompt action for wiki documentation with validation and commit requirements.
Create a typed action
Add a ProtoScript action that validates a wiki page and reports scoped git status with a user-oriented infinitive phrase.
Create a service or provider
Model a configured reporting database as a service, or add a provider-native model backend as a provider module without exposing secrets.
Common mistakes
- Using prompt text for durable facts instead of ontology memory.
- Using memory for secrets; secret values belong in secret storage.
- Creating a service for one simple stateless command.
- Creating one flat tool for a configured external account that needs identity and lifecycle.
- Forgetting semantic phrases, skill manifests, provider catalog patterns, or scoped commits.