@archships/dim-plugin-skills

Official metadata-first skills plugin for dim-agent-sdk.

What it does

• scans skills from ~/.agents/skills by default
• optionally keeps ${cwd}/.agents/skills as a compatibility root
• merges extra roots with stable priority
• injects a <skills_instructions> metadata segment into every model turn
• lists each skill with name and description
• documents skill: name as a direct trigger for the skill tool
• exposes a single skill tool so the model can load full instructions by name
• returns full SKILL.md instruction bodies as the skill tool result
• exports installSkillBundle() for host-side skill installation

Skill layout

Each skill is a directory with a required SKILL.md file and optional bundled resources:

demo-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/

SKILL.md must start with YAML frontmatter:

---
name: "demo-skill"
description: "Short description"
allowedTools:
  - Read
  - Grep
  - Bash(git:*)
---

# Demo Skill

Read references/checklist.md before acting.
Run scripts/lint.sh with the exec tool when needed.

Usage

import { createAgent, createModel } from '@archships/dim-agent-sdk'
import { createSkillsPlugin } from '@archships/dim-plugin-skills'

const agent = createAgent({
  model: createModel(adapter),
  cwd: process.cwd(),
  plugins: [
    createSkillsPlugin({
      userSkillsDir: '~/.agents/skills',
      roots: ['/absolute/path/to/shared-skills'],
      includeWorkspaceCompatRoot: true,
    }),
  ],
})

Runtime behavior

• <skills_instructions> metadata is always injected into the runtime system prompt.
• The metadata prompt lists skill names and descriptions, then tells the model to call skill.
• User input containing skill: name tells the model to call skill({ skill_name: 'name' }).
• Full skill instructions are returned immediately by skill({ skill_name }) in the same model turn, prefixed with the skill's absolute SKILL.md path.
• Only an explicit skill({ skill_name }) tool call loads a skill.

Session controller

The plugin exposes a host-facing controller through session.getPlugin('skills'):

const controller = session.getPlugin('skills')
await controller?.getState()
await controller?.refreshCatalog()

Installer helper

Use installSkillBundle() from host code or settings UI to normalize a bundle into the canonical install root:

import { installSkillBundle } from '@archships/dim-plugin-skills'

await installSkillBundle('/tmp/incoming/my-review-skill', {
  targetRoot: '~/.agents/skills',
  replaceExisting: false,
})

Behavior notes:

• the target directory is always ${targetRoot}/${frontmatter.name}
• if the source directory name differs from frontmatter.name, only the installed copy is renamed
• runtime catalog caches must be refreshed with controller.refreshCatalog() after install / remove

Notes

• allowedTools is normalized to current SDK tool names and exposed as metadata only
• scoped shell forms such as Bash(git:*) degrade to exec; command-level exec restrictions are not enforced by this plugin
• bundled files are not eagerly inlined into the prompt; loaded skills should reference them relative to the SKILL.md directory and use existing tools such as read or exec