Harness Skills

Versioned operating knowledge for long-running agents

Harness Skills are immutable administrator-published instruction packages. Every version belongs to one principal, is addressed by exact name@version, and is loaded by that principal's Harness agents during activation.

"_HarnessSkills": "[email protected],invoice-rules@2026-08-01"

Why Skills use typed storage

ZIP is transport only. The Host validates the upload, normalizes its contents, and writes a manifest plus independent resources to the principal-scoped fabrcore.harness-skills container.

packages/{name}/{version}/manifest
packages/{name}/{version}/resources/{resourceId}

• Publication writes resources first, the manifest as the commit marker, then the principal's catalog entry.
• An interrupted publish without a committed manifest is invisible.
• Deletion removes the manifest first, then the catalog entry, followed by best-effort resource cleanup.
• Skills have no TTL. They are removed only through explicit deletion.
• Localhost Orleans storage is process-local; use SQL Server, Azure Storage, or another durable provider for restart persistence.

Package shape

Upload one ZIP with SKILL.md at the root or inside one matching top-level directory.

SKILL.md
references/policy.md

policy-review/SKILL.md
policy-review/references/policy.md

The YAML frontmatter name must exactly match the route name.

---
name: policy-review
description: Review a proposed policy against the approved checklist.
compatibility: FabrCore 1.7.1+
---

# Policy review

Load references/checklist.md, evaluate every item, and report evidence for failures.

Validation and limits

Accepted textual resources are .md, .json, .yaml, .yml, .csv, .xml, and .txt. The Host rejects executables, scripts, symlinks, traversal or absolute paths, backslashes, duplicate normalized paths, multiple roots, invalid UTF-8, and malformed frontmatter.

Administration API

GET    /fabrcoreapi/admin/v1/principals/{principalId}/skills
GET    /fabrcoreapi/admin/v1/principals/{principalId}/skills/{name}/versions/{version}
PUT    /fabrcoreapi/admin/v1/principals/{principalId}/skills/{name}/versions/{version}
DELETE /fabrcoreapi/admin/v1/principals/{principalId}/skills/{name}/versions/{version}

All endpoints require the FabrCoreAdmin bearer policy. PUT uses Content-Type: application/zip. Publishing the same digest to the same version is idempotent; different bytes at an existing version return 409 Conflict.

Typed SDK

await using var package = File.OpenRead("policy-review.zip");

var published = await hostApi.PublishHarnessSkillAsync(
    principalId: "contoso",
    name: "policy-review",
    version: "1.2.0",
    zipStream: package,
    cancellationToken);

var skills = await hostApi.ListHarnessSkillsAsync(
    "contoso", cancellationToken);

The client also provides GetHarnessSkillAsync and DeleteHarnessSkillAsync. Configure its HTTP authentication for the Host's administration policy.

Runtime behavior

• CreateFabrCoreHarnessAgent resolves Skills only for the current agent principal.
• Every pinned manifest is loaded and validated during OnInitialize; missing or corrupt references are reported together.
• Manifests are cached for the activation. Resources are read lazily through read_skill_resource, integrity-checked, then cached.
• The model receives load_skill and read_skill_resource. Stored Skills do not expose run_skill_script.
• Deleting a version prevents new activations from loading it. An already active agent retains its immutable activation-local copy.
• Changing a pinned version requires agent reconfiguration or eviction so initialization runs again.

Security model

Skill publication is an administrative supply-chain operation. The API records actor, target principal, skill reference, digest, outcome, and command id without placing instruction content in the audit log. Exact versions and content digests make deployments reviewable and reproducible.