# How Paperclip AI Loads Skills and Injects Them into Agent Contexts

> Learn how Paperclip AI loads skills from its catalog, injects them as JSON metadata into agent prompts, and mounts source files into the execution sandbox for efficient agent context.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: internals
- Published: 2026-08-12

---

**Paperclip AI discovers skills from the catalog, resolves versioned bundles at runtime, and injects them into agent prompts as JSON metadata while mounting source files into the execution sandbox.**

Paperclip AI treats a **skill** as a reusable TypeScript module that agents invoke during task execution. The platform implements a three-stage pipeline—discovery, runtime loading, and prompt injection—to dynamically **load skills and inject them into agent contexts** on every heartbeat. This architecture keeps skill definitions declarative while enabling dynamic, version-specific execution.

## Skill Discovery and Catalog Registration

When administrators create or install a skill, the **skills catalog** (`@paperclipai/skills-catalog`) processes the module to extract its public API and store metadata for runtime retrieval.

### Parsing skill.yaml and package.json

The catalog builder ([`packages/skills-catalog/src/catalog-builder.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/skills-catalog/src/catalog-builder.ts)) reads the skill's declarative configuration. It parses [`skill.yaml`](https://github.com/paperclipai/paperclip/blob/main/skill.yaml) and [`package.json`](https://github.com/paperclipai/paperclip/blob/main/package.json) to identify exported functions, parameters, and entry points.

### Generating the SkillDescriptor

The builder generates a **SkillDescriptor**—a JSON object containing the skill's name, description, and function signatures. This descriptor is persisted to the `company_skills` table in the database, making the skill available for assignment to specific agents and runs.

## Runtime Loading During Heartbeat

On every heartbeat, the server resolves which skills the current agent run requires and prepares their execution bundles for immediate injection.

### Version Resolution with loadSkillTestRunAssignmentScope

The server-side helper `loadSkillTestRunAssignmentScope` (defined in [`server/src/routes/company-skills.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/company-skills.ts)) validates company permissions and resolves the specific version to load. The function accepts `companyId`, `skillId`, and `runId` parameters. If no version is pinned, it defaults to the latest available version automatically.

### Fetching Source Bundles

The function calls the **skill loader** ([`packages/adapter-utils/src/skill-loader.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/adapter-utils/src/skill-loader.ts)) to retrieve source files from their storage location—whether local filesystem, GitHub repository, or catalog ZIP. It returns a **SkillRuntimeInfo** object containing the `bundlePath`, `descriptor`, `env` bindings, and `versionId`.

```typescript
// Server-side: Resolve skill for current heartbeat
import { loadSkillTestRunAssignmentScope } from "./company-skills";

async function resolveSkillRuntime(
  companyId: string,
  skillId: string,
  runId: string,
) {
  // Returns SkillRuntimeInfo with bundle and descriptor
  const skillInfo = await loadSkillTestRunAssignmentScope(
    companyId,
    skillId,
    runId,
  );
  return skillInfo; // { bundlePath, descriptor, env, versionId }
}

```

## Prompt Injection and Sandbox Setup

The agent runtime converts the **SkillRuntimeInfo** into LLM-visible context and prepares the execution environment for safe skill invocation.

### Injecting Metadata into Prompts

The **sandbox-managed runtime** ([`packages/adapter-utils/src/sandbox-managed-runtime.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/adapter-utils/src/sandbox-managed-runtime.ts)) replaces the `{{skillMetadata}}` placeholder in the prompt template with a JSON-serialized **SkillDescriptor**. This allows the LLM to see available function names, parameters, and descriptions according to the runtime specification in [`doc/spec/agents-runtime.md`](https://github.com/paperclipai/paperclip/blob/main/doc/spec/agents-runtime.md).

### Mounting Skills into the Sandbox

The `injectSkillBundle` function copies the skill's source files from `bundlePath` into the sandbox directory. This enables the agent to dynamically import and execute the skill code when the model decides to invoke it.

```typescript
// Runtime-side: Inject into prompt and sandbox
import { injectSkillBundle } from "./sandbox-managed-runtime";

async function prepareAgentContext(
  baseTemplate: string,
  skillInfo: SkillRuntimeInfo,
) {
  // Replace placeholder with skill API description
  const prompt = baseTemplate.replace(
    "{{skillMetadata}}",
    JSON.stringify(skillInfo.descriptor),
  );

  // Mount source files for execution
  await injectSkillBundle(skillInfo.bundlePath);
  return prompt;
}

```

### SkillDescriptor Structure

The injected metadata follows a standardized schema that describes the skill's public interface:

```json
{
  "name": "review",
  "description": "Automated code-review helper",
  "functions": [
    {
      "name": "suggestChanges",
      "parameters": {
        "type": "object",
        "properties": {
          "diff": { "type": "string" }
        },
        "required": ["diff"]
      }
    }
  ]
}

```

## Summary

- **Discovery**: The catalog builder ([`packages/skills-catalog/src/catalog-builder.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/skills-catalog/src/catalog-builder.ts)) parses [`skill.yaml`](https://github.com/paperclipai/paperclip/blob/main/skill.yaml) to create **SkillDescriptor** records stored in the `company_skills` table.
- **Loading**: `loadSkillTestRunAssignmentScope` in [`server/src/routes/company-skills.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/company-skills.ts) resolves versions and fetches source bundles from storage during each heartbeat.
- **Injection**: The runtime inserts JSON metadata into prompts via the `{{skillMetadata}}` placeholder and mounts files into the sandbox using `injectSkillBundle` from [`packages/adapter-utils/src/sandbox-managed-runtime.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/adapter-utils/src/sandbox-managed-runtime.ts).
- **Execution**: Agents reference injected skills by name in their prompts and execute them within the isolated sandbox environment.

## Frequently Asked Questions

### What file format defines a Paperclip AI skill?

Skills are defined by a [`skill.yaml`](https://github.com/paperclipai/paperclip/blob/main/skill.yaml) file that declares the module's public API, alongside a standard [`package.json`](https://github.com/paperclipai/paperclip/blob/main/package.json) for dependency management. The catalog builder parses both files to generate the **SkillDescriptor** stored in the database.

### How does Paperclip AI handle skill versioning?

The `loadSkillTestRunAssignmentScope` function checks for pinned versions in the run configuration. If none is specified, it automatically resolves to the latest version available in the catalog, ensuring agents use the most current skill iterations while supporting explicit version locking when needed.

### Where are skill files stored during agent execution?

The `injectSkillBundle` function copies source files into the execution sandbox directory managed by [`packages/adapter-utils/src/sandbox-managed-runtime.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/adapter-utils/src/sandbox-managed-runtime.ts). This sandboxed approach isolates skill code while making it available for dynamic import during the agent's runtime session.

### Can skills be loaded from external repositories?

Yes. The skill loader supports multiple storage backends including local filesystem paths, GitHub repositories, and catalog ZIP bundles. The system resolves the appropriate source based on the skill's registration configuration in the **skills catalog**, allowing teams to distribute skills via version control or the centralized catalog.