How-to

Add a prompt skill

Create a reusable instruction, checklist, review, or operational workflow that the Buffaly agent can discover and run as a normal action.

In Buffaly, the markdown prompt is only one part of the skill. It becomes reusable when it is registered in ontology as a prompt action with a name, description, prompt path, skill kind, version, and semantic action phrases.

Quick answer

The easiest path is to ask Buffaly to create the prompt skill for you. Give it the goal, source of truth, target skill folder, prompt name, action phrases, safety rules, and validation expectations.

Create a new Buffaly prompt skill called ToReviewReleaseChecklist for reviewing release readiness. Put the prompt under the appropriate skill-local Prompts folder, register it as a prompt action with two semantic infinitive phrases, validate the project, and report the changed files. Do not store any secrets in the prompt.

The Buffaly agent should inspect existing skill layout, write or update the prompt markdown, register the prompt action prototype, validate discovery or loading where possible, and report exactly what changed.

When to use a prompt skill

Use a prompt skill when the reusable value is mostly trusted instructions: review checklists, documentation writing rules, investigation workflows, deployment runbooks, drafting, summarization, critique, or operational procedures that need judgment.

Need	Better Buffaly boundary
Durable fact, preference, contact, environment, or account	Ontology memory
Repeatable procedure that is still evolving	Workflow memory
Typed parameters, validation, or executable logic	ProtoScript action
Deterministic SDK, protocol, or file behavior	Native C# or DLL-backed tool
Lifecycle, identity, state, configuration, or related methods	Service or MCP-backed service instance
UI, routes, JsonWs artifacts, or static assets	Web module

For the full decision tree, see Adding skills, services, and tools.

Prompt action registration

A prompt file alone is not discoverable. A prompt action prototype gives Buffaly the metadata it needs: prototype name, prompt flag, skill kind, version, prompt path, description, and semantic infinitive phrases.

[SemanticProgram.InfinitivePhrase("to refresh a buffaly installation from source")]
[SemanticProgram.InfinitivePhrase("to update a buffaly installed root after source changes")]
[SemanticEntity("buffaly install refresh workflow")]
prototype ToRefreshBuffalyInstallFromSourceSkill : PromptAction
{
    IsPromptAction = true;
    SkillKind = "prompt";
    SkillVersion = "1.0.0";
    PromptPath = @"Nodes/Personal/VisualStudioSolutions/Buffaly/Prompts/RefreshBuffalyInstallFromSource.prompt.md";
    Description = @"Refresh one installed Buffaly runtime root from source/build outputs using the canonical updater workflow.";
}

Older implementation paths may still use OpsAgent. Treat that as a legacy implementation path name; user-facing prose should say Buffaly agent.

Prompt markdown anatomy

The prompt file should be practical and operational. Include verified instructions only, and never paste secrets, bearer tokens, OAuth tokens, passwords, API keys, or customer-sensitive data into the prompt.

Title: Refresh Buffaly install from source

Goal
- State what the workflow accomplishes.
- Say when to use it.

Canonical updater
- Point to the authoritative script, service, command, or implementation path.

Execution protocol
1. Identify the changed component.
2. Choose the target environment.
3. Run the narrow command or workflow.

Validation protocol
1. Check a safe status or response.
2. Verify generated artifacts or output.
3. Report exact evidence.

Known caveats
- List lock, credential, deployment, or safety constraints.

Reporting requirements
- State what Buffaly must report when done or blocked.

Manual path

Choose the owning skill folder; keep prompt files skill-local where possible.
Add or update the markdown prompt under a Prompts folder.
Add or update one prompt-action prototype in the appropriate .pts file.
Set IsPromptAction, SkillKind, SkillVersion, PromptPath, and Description.
Add at least one user-like SemanticProgram.InfinitivePhrase.
Add SemanticEntity only when the workflow or target is meaningfully entity-like.
Validate that PromptPath is correct from the active Buffaly agent project root.
Compile or reload the project/runtime before relying on the action.

When available, prefer the typed authoring path such as UpsertPromptSkill(...), which writes the prompt file and updates the prompt-action prototype while keeping paths inside the project directory.

Discovery and validation

Prompt skills use the same action-loading model as other Buffaly capabilities: semantic phrase, action prototype, natural-language request, candidate action search, action loading, and prompt-backed execution.

Search candidate actions for the phrase users will say and confirm the new prompt action appears.
List actions for the relevant skill and confirm prototype name, description, and prompt path.
Load the prompt action tool without running destructive work.
Run the prompt skill on a harmless sample and report exactly which prompt file was used.

Common mistakes and troubleshooting

Only creating markdown

A prompt file without action metadata is not discoverable.

Missing semantic phrases

Use user-like infinitive phrases, not only internal names.

Wrong prompt path

Point from the active Buffaly agent project layout, not a temporary session folder.

Stale runtime

After changing .pts action metadata, reload or rebuild before testing discovery.

Context prompts Next: add a ProtoScript skill Choose a capability boundary Back to docs