Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

7.8 KB
Raw Blame
import {
  SKILL_AUTHORING_WARNING_CODES,
  SKILL_INSTALL_WARNING_CODES,
  type SkillLocationId,
  SkillLocationIdSchema,
  type SkillScope,
} from '@inkeep/open-knowledge-core';
import { parseSkillsShSource } from '@inkeep/open-knowledge-core/skills-catalog';
import { z } from 'zod';
import type { LocalApiDispatch } from '../../http/local-api-dispatch.ts';
import type { AgentIdentity } from '../agent-identity.ts';
import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';
import {
  AUTHORING_WARNING_CODE_GLOSS,
  agentIdentityFields,
  alignWarningCodes,
  apiTarget,
  httpPost,
  INSTALL_WARNING_CODE_GLOSS,
  outputSchemaWithText,
  ROUTED_CWD_DESCRIPTION,
  requireProjectServer,
  summaryArgSchema,
  textPlusStructured,
  textResult,
  warningCodesContract,
  warningsFieldContract,
} from './shared.ts';
import { SkillScopeArg } from './verb-schemas.ts';

const KNOWN_CODES: ReadonlySet<string> = new Set<string>([
  ...SKILL_AUTHORING_WARNING_CODES,
  ...SKILL_INSTALL_WARNING_CODES,
]);

const DESCRIPTION = [
  'Import an external agentskills.io/skills.sh skill as managed content. Requires the Hocuspocus server. source accepts a full skills.sh page URL (including website catalogs), owner/repo[/subpath], git URL, or local/file:// path. skill picks one from a multi-skill source. scope: project (default, versioned/shared) or global (user-wide, unversioned).',
  'Writes the .agents/skills/<name>/ hub with provenance in .ok/skills-lock.json. Scripts are NEVER executed. add selects editor locations; import always places the skill somewhere. Use install later to change placement/form/source. Name collisions use <name>-imported, never overwrite; identical content-hash re-import is a no-op.',
].join('\n');

interface ImportDeps {
  serverUrl: ServerUrlOrResolver;
  config: ConfigOrResolver;
  resolveCwd: (explicit?: string) => Promise<string>;
  identityRef?: { current: AgentIdentity };
  localApi?: LocalApiDispatch;
}

export function register(server: ServerInstance, deps: ImportDeps): void {
  server.registerTool(
    'import',
    {
      description: DESCRIPTION,
      inputSchema: {
        source: z
          .string()
          .min(1)
          .describe(
            'Full skills.sh skill-page URL (`https://www.skills.sh/<owner>/<repo>/<skill>`, or `https://www.skills.sh/site/<hostname>/<skill>` for a website catalog), `owner/repo[/subpath]`, a git URL, or a local / `file://` path.',
          ),
        skill: z.string().min(1).optional().describe('Pick one skill from a multi-skill source.'),
        add: z
          .array(SkillLocationIdSchema)
          .min(1)
          .describe(
            'REQUIRED — where the imported skill goes. Editor ids (`claude` … `pi`), `agents` (the vendor-neutral hub), or a custom root path (".team/skills"). Same vocabulary as `install`. A skill acquired and placed nowhere is not a state worth having, so this is not optional.',
          ),
        mode: z
          .enum(['copy', 'link'])
          .optional()
          .describe(
            'The form for the locations in `add`. "link": a symlink to the source. "copy": an independent folder, refreshed on watcher/startup sync while unedited; hand edits fork it. Omit to follow the form the skill already uses.',
          ),
        scope: SkillScopeArg.optional(),
        summary: summaryArgSchema,
        cwd: z.string().optional().describe(ROUTED_CWD_DESCRIPTION),
      },
      outputSchema: outputSchemaWithText({
        name: z
          .string()
          .optional()
          .describe('Managed skill name created or matched by the import.'),
        path: z
          .string()
          .optional()
          .describe('Project-relative path of the imported skill bundle (under `.agents/skills`).'),
        alreadyImported: z
          .boolean()
          .optional()
          .describe('True when an identical content hash already existed and no files changed.'),
        collisionRenamedFrom: z
          .string()
          .optional()
          .describe(
            'Original upstream skill name when a local collision forced an `-imported` rename.',
          ),
        warnings: z
          .array(z.string())
          .optional()
          .describe(
            `Non-fatal warnings from BOTH steps: the acquire (skipped unsupported bundle files) first, then the placement \`add\` runs. ${warningsFieldContract('each step')} One step sending an unreadable shape replaces only its own slice of this list; the other step's text still comes through.`,
          ),
        warningCodes: z
          .array(z.enum([...SKILL_AUTHORING_WARNING_CODES, ...SKILL_INSTALL_WARNING_CODES]))
          .optional()
          .describe(
            `${warningCodesContract('either step')} Authoring codes (from the imported SKILL.md): ${AUTHORING_WARNING_CODE_GLOSS} Placement codes: ${INSTALL_WARNING_CODE_GLOSS}`,
          ),
      }),
    },
    async (args: {
      source: string;
      skill?: string;
      add: SkillLocationId[];
      mode?: 'copy' | 'link';
      scope?: SkillScope;
      summary?: string;
      cwd?: string;
    }) => {
      const context = await requireProjectServer(
        deps.resolveCwd,
        deps.config,
        deps.serverUrl,
        args.cwd,
      );
      if (!context.ok) return context.result;

      const result = await httpPost(apiTarget(context.url, deps.localApi), '/api/skill/import', {
        source: args.source,
        ...(args.skill !== undefined ? { skill: args.skill } : {}),
        install: false,
        ...(parseSkillsShSource(args.source) !== null ? { marketplace: true } : {}),
        ...(args.scope !== undefined ? { scope: args.scope } : {}),
        ...(args.summary !== undefined ? { summary: args.summary } : {}),
        ...agentIdentityFields(deps.identityRef?.current),
      });
      if (!result.ok) {
        const detail = typeof result.detail === 'string' ? ` (${result.detail})` : '';
        return textResult(`Error: ${result.error}${detail}`, true);
      }

      const name = typeof result.name === 'string' ? result.name : args.source;
      const placed = await httpPost(apiTarget(context.url, deps.localApi), '/api/skill/install', {
        ...(args.scope !== undefined ? { scope: args.scope } : {}),
        name,
        add: args.add,
        ...(args.mode !== undefined ? { mode: args.mode } : {}),
        ...(args.summary !== undefined ? { summary: args.summary } : {}),
        ...agentIdentityFields(deps.identityRef?.current),
      });
      if (!placed.ok) {
        return textResult(
          `Imported "${name}", but placing it failed: ${placed.error}. Run \`install\` to retry the placement.`,
          true,
        );
      }
      const alreadyImported = result.alreadyImported === true;
      const renamedFrom =
        typeof result.collisionRenamedFrom === 'string' ? result.collisionRenamedFrom : undefined;
      const acquired = alignWarningCodes(result.warnings, result.warningCodes, KNOWN_CODES);
      const projected = alignWarningCodes(placed.warnings, placed.warningCodes, KNOWN_CODES);
      const warnings = [...acquired.warnings, ...projected.warnings];
      const line = alreadyImported
        ? `Skill "${name}" was already imported (identical content); its placement was applied.`
        : `Imported "${name}"${renamedFrom ? ` (renamed from "${renamedFrom}" — the name was taken)` : ''} into .agents/skills as content. Scripts shown, never run. Use \`install\` to change where it lives.`;
      return textPlusStructured([line, ...warnings].join('\n'), {
        name,
        path: typeof result.path === 'string' ? result.path : undefined,
        alreadyImported,
        ...(renamedFrom ? { collisionRenamedFrom: renamedFrom } : {}),
        warnings,
        ...(acquired.warningCodes && projected.warningCodes
          ? { warningCodes: [...acquired.warningCodes, ...projected.warningCodes] }
          : {}),
      });
    },
  );
}