Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(api): optionally include skill file contents (#18826)

tobi_kl180e54f62e51
diff --git a/fern/apis/server/definition/unstable/skills.yml b/fern/apis/server/definition/unstable/skills.yml
index 7fadb32e09..16bce4c874 100644
--- a/fern/apis/server/definition/unstable/skills.yml
+++ b/fern/apis/server/definition/unstable/skills.yml
@@ -42,7 +42,7 @@ service:
type: SkillVersion
get:
- docs: Resolve a skill's metadata and file manifest by version or label. Defaults to the production label. Use each file's sha256Hash with getFileContents, individually or in batches across manifests.
+ docs: Resolve a skill's metadata and file manifest by version or label. Defaults to the production label. Set includeContent to return file contents inline, or use each file's sha256Hash with getFileContents.
method: GET
path: /skills/{skillName}
path-parameters:
@@ -52,6 +52,9 @@ service:
query-parameters:
version: optional<integer>
label: optional<string>
+ includeContent:
+ type: optional<boolean>
+ docs: Include UTF-8 text content in each file. Defaults to false.
response: SkillVersion
update:
@@ -155,6 +158,9 @@ types:
sha256Hash: string
contentType: string
contentLength: long
+ content:
+ type: optional<string>
+ docs: UTF-8 text content, included when fetching a skill with includeContent enabled.
SkillFileContentsResponse:
properties:
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index 32bb462938..cca8e67abb 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -7219,8 +7219,8 @@ paths:
get:
description: >-
Resolve a skill's metadata and file manifest by version or label.
- Defaults to the production label. Use each file's sha256Hash with
- getFileContents, individually or in batches across manifests.
+ Defaults to the production label. Set includeContent to return file
+ contents inline, or use each file's sha256Hash with getFileContents.
operationId: unstable_skills_get
tags:
- UnstableSkills
@@ -7242,6 +7242,13 @@ paths:
schema:
type: string
nullable: true
+ - name: includeContent
+ in: query
+ description: Include UTF-8 text content in each file. Defaults to false.
+ required: false
+ schema:
+ type: boolean
+ nullable: true
responses:
'200':
description: ''
@@ -14636,6 +14643,12 @@ components:
contentLength:
type: integer
format: int64
+ content:
+ type: string
+ nullable: true
+ description: >-
+ UTF-8 text content, included when fetching a skill with
+ includeContent enabled.
required:
- id
- path
diff --git a/web/src/features/public-api/types/unstable-skills.ts b/web/src/features/public-api/types/unstable-skills.ts
index 772481ee26..a472ad6ea8 100644
--- a/web/src/features/public-api/types/unstable-skills.ts
+++ b/web/src/features/public-api/types/unstable-skills.ts
@@ -1,6 +1,17 @@
-import { SkillVersionFileReferenceSchema } from "@langfuse/shared";
+import {
+ SkillVersionFileReferenceSchema,
+ SkillVersionSchema,
+} from "@langfuse/shared";
import { z } from "zod/v4";
+export const GetSkillResponseSchema = SkillVersionSchema.extend({
+ files: z.array(
+ SkillVersionSchema.shape.files.element.extend({
+ content: z.string().optional(),
+ }),
+ ),
+});
+
export const GetSkillFileContentsInputSchema = z.object({
sha256Hashes: z
.array(SkillVersionFileReferenceSchema.shape.sha256Hash)
diff --git a/web/src/features/skills/server/skill-service.ts b/web/src/features/skills/server/skill-service.ts
index f3eb344465..f5bf1f80a2 100644
--- a/web/src/features/skills/server/skill-service.ts
+++ b/web/src/features/skills/server/skill-service.ts
@@ -250,9 +250,26 @@ export class SkillService {
projectId: string;
name: string;
selector: SkillSelector;
+ includeContent?: boolean;
}) {
const skill = await this.findSkillVersion(params);
- return serializeVersion(skill);
+ const version = serializeVersion(skill);
+ if (!params.includeContent) return version;
+
+ const { data } = await this.getFileContents({
+ projectId: params.projectId,
+ sha256Hashes: version.files.map((file) => file.sha256Hash),
+ });
+ const contentByHash = new Map(
+ data.map(({ sha256Hash, content }) => [sha256Hash, content]),
+ );
+ return {
+ ...version,
+ files: version.files.map((file) => ({
+ ...file,
+ content: contentByHash.get(file.sha256Hash),
+ })),
+ };
}
async loadResource(params: {
diff --git a/web/src/pages/api/public/unstable/skills/[skillName]/index.ts b/web/src/pages/api/public/unstable/skills/[skillName]/index.ts
index 0db85b3de7..2e4fbab50e 100644
--- a/web/src/pages/api/public/unstable/skills/[skillName]/index.ts
+++ b/web/src/pages/api/public/unstable/skills/[skillName]/index.ts
@@ -11,9 +11,16 @@ import {
withMiddlewares,
} from "@/src/features/public-api/server";
import { SkillService } from "@/src/features/skills/server";
+import { GetSkillResponseSchema } from "@/src/features/public-api/types/unstable-skills";
const querySchema = SkillSelectorSchema.and(
- z.object({ skillName: SkillNameSchema }),
+ z.object({
+ skillName: SkillNameSchema,
+ includeContent: z
+ .enum(["true", "false"])
+ .optional()
+ .transform((value) => value === "true"),
+ }),
);
export default withMiddlewares({
@@ -42,13 +49,16 @@ export default withMiddlewares({
name: "Get Skill",
action: "skills:read",
querySchema,
- responseSchema: SkillVersionSchema,
+ responseSchema: GetSkillResponseSchema,
rateLimitResource: "public-api",
- fn: async ({ query, auth }) =>
- new SkillService(prisma).get({
+ fn: async ({ query, auth, res }) => {
+ if (query.includeContent) res.setHeader("Cache-Control", "no-store");
+ return new SkillService(prisma).get({
projectId: auth.scope.projectId,
name: query.skillName,
selector: query,
- }),
+ includeContent: query.includeContent,
+ });
+ },
}),
});