@kestrel-agents/workspace-skills

Use this package when a Kestrel host needs to install portable agent guidance into a persistent workspace.

Install

Bash

pnpm add @kestrel-agents/workspace-skills@0.8.5

Create a workspace manager

TypeScript

import { WorkspaceSkillManager } from "@kestrel-agents/workspace-skills";
 
const skills = new WorkspaceSkillManager(
  { workspaceId: "project-1", workspaceRoot: "/workspace/project-1" },
  { isWorkspaceIdle: async () => activeRuns === 0 },
);
 
await skills.install({
  gitUrl: "https://github.com/example/agent-skills.git",
  branch: "main",
  path: "skills/review",
});

Discover, install, and verify skills

Discover candidate sources outside the runtime, then install an exact repository/branch/path through the manager. Verify the resolved commit, content digest, root SKILL.md, metadata, and active/pending state before exposing guidance to a run.

Ownership and portability

The workspace owner chooses which portable guidance belongs to the project. The immutable installed revision travels with workspace provenance; provider credentials and host policy do not.

Runtime guarantees

Sources must use credential-free public HTTPS Git URLs.
A package must contain a root SKILL.md with valid name and description YAML frontmatter.
Published revisions are immutable and identified by commit and SHA-256 content digest.
Failed refreshes retain the last verified revision.
Installs, updates, and removals may remain pending until the host reports the workspace idle.
Installation never runs hooks or code from the source repository.

Skill instructions are guidance only. The host remains responsible for its tool, credential, network, and filesystem policy.

Security and workspace boundaries

Resolve paths under the declared workspace, reject symlink escapes, install only credential-free public HTTPS sources, and never execute source hooks. Tool access still comes from the active Kestrel profile.

Errors and compatibility

Surface invalid metadata, unreachable sources, digest mismatch, busy workspace, and failed refresh distinctly. Use the exact 0.8 package line and retain the last verified revision when a refresh cannot be accepted.