@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 an Available Skills metadata segment into every model turn
• exposes skill_list and skill_control so the model can activate skills itself
• injects full SKILL.md instruction bodies only after activation
• 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

Current skill root: ${SKILL_ROOT}
Skills directory: ${SKILLS_DIR}

Read ${SKILL_ROOT}/references/checklist.md before acting.
Run ${SKILL_ROOT}/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

• Available Skills metadata is always injected into the runtime system prompt.
• Full skill instructions are injected only after activation.
• The model should call skill_list and skill_control to inspect or activate skills.
• skill_control changes take effect on the next model loop in the same run.
• activeSkills are persisted through save() / restoreSession().
• $skill-name no longer auto-activates a skill.

Session controller

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

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

const controller = session.getPlugin<SkillsSessionController>('skills')
await controller?.activate('demo-skill')
await controller?.deactivate('demo-skill')
await controller?.deactivateAll()
await controller?.refreshCatalog()

Compatibility aliases remain available for one release:

await controller?.enable('demo-skill')
await controller?.disable('demo-skill')
await controller?.disableAll()

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; skills should reference them via ${SKILL_ROOT} and existing tools such as read or exec