스킬 소스 작성

스킬이 디스크가 아닌 S3, 데이터베이스 또는 private registry에 있다면 SkillSource를 구현하여 withSkills에 제공합니다. 바이트만 다루는 작은 interface이므로 edge를 포함한 어디에서나 작동합니다.

이 페이지에서는 최소 소스를 보여준 다음 패키지에 포함된 conformance suite로 올바르게 작동하는지 검증하는 방법을 설명합니다.

최소 소스

소스에는 두 메서드가 필요합니다. list는 카탈로그를 반환하고 load는 한 스킬의 SKILL.md 본문을 반환합니다. 다음은 S3 기반 예시입니다.

import type { SkillSource } from '@tanstack/ai-skills'

export function s3Skills(bucket: S3Bucket): SkillSource {
  return {
    async list() {
      const index = await bucket.getJSON('skills/index.json')
      return index.map((s) => ({ name: s.name, description: s.description }))
    },
    async load(name) {
      return bucket.getText(`skills/${name}/SKILL.md`)
    },
  }
}

이를 withSkills(s3Skills(bucket))에 직접 전달합니다. 미들웨어가 load의 반환값에서 frontmatter를 제거하므로 원본 SKILL.md를 반환하세요.

리소스와 revision 추가

두 가지 선택적 메서드로 소스를 개선할 수 있습니다.

revision()은 콘텐츠가 변경될 때만 바뀌는 stable string을 반환합니다. withSkills는 chat() 호출마다 한 번 나열하며 revision()에 캐시하지 않습니다. combinator, 자체 cache 또는 이후 카탈로그 memo가 이를 키로 사용할 수 있도록 추가하세요( bucket ETag 또는 콘텐츠 hash).
listResources와 readResource는 스킬의 번들 파일을 노출하여 read_skill_resource가 이를 읽을 수 있습니다.

import type { SkillSource } from '@tanstack/ai-skills'

export function s3Skills(bucket: S3Bucket): SkillSource {
  return {
    revision: () => bucket.getText('skills/index.etag'),
    async list() {
      /* as above */
    },
    async load(name) {
      return bucket.getText(`skills/${name}/SKILL.md`)
    },
    async listResources(name) {
      return bucket.listKeys(`skills/${name}/references/`)
    },
    async readResource(name, path) {
      return bucket.getBytes(`skills/${name}/${path}`)
    },
  }
}

소스가 바이트만 다루는 것은 의도된 설계입니다. path 필드가 없으므로 데이터베이스나 registry 소스도 파일 시스템을 전제로 덧붙인 부차적인 방식이 아니라 first-class citizen입니다.

conformance suite로 검증

어댑터 코드는 미묘하게 잘못 작성하기 쉽습니다(없는 스킬이 throw하는 대신 비어 있는 값을 반환하거나, 리소스 경로가 스킬 root를 벗어나는 경우 등). 패키지는 추측이 아닌 동작을 테스트할 수 있도록 conformance suite를 제공합니다.

suite가 기대하는 fixture로 소스를 초기화한 다음(hello 콘텐츠의 references/note.md 리소스를 가진 alpha 스킬과 beta 스킬), 실행합니다.

import { runSkillSourceConformance } from '@tanstack/ai-skills/testing'
import { s3Skills } from './s3-skills'

runSkillSourceConformance(() => s3Skills(makeTestBucket()), 's3')

suite는 운영 환경에서 문제를 일으키는 다음 항목을 확인합니다.

없는 스킬 이름은 throw하며 비어 있는 값을 반환하지 않습니다.
리소스가 로드되고 ../../etc/passwd 같은 경로가 거부됩니다.
동일한 콘텐츠에서 revision()이 안정적입니다.
동시 list() 호출이 일관성을 유지합니다.
스크립트 바이트가 올바르게 반환됩니다(후속 릴리스에서 스크립트 실행이 추가되어도 소스가 계속 작동하도록 합니다).

통과하면 소스를 안전하게 withSkills에 전달할 수 있습니다.

다음 단계

Skill sources — 기본 제공 소스와 combinator를 설명합니다.
Portable Agent Skills — 소스가 제공하는 미들웨어와 load_skill 흐름을 설명합니다.

최소 소스​

리소스와 revision 추가​

conformance suite로 검증​

다음 단계​

최소 소스

리소스와 revision 추가

conformance suite로 검증

다음 단계