Custom Skills

Skills are discoverable, loadable packs of instructions and assets. Each skill lives in its own directory with a SKILL.md file that contains YAML frontmatter and markdown instructions.

Skill format

The directory name must match the skill name in frontmatter. Use allowed-tools to scope what the agent can call when the skill is active.

.skills/
  incident-response/
    SKILL.md
    scripts/
      triage.py
    references/
      playbook.md

---
name: incident-response
description: Triage host compromise signals and summarize next actions.
allowed-tools: read_logs run_skill_script
license: MIT
compatibility: dreadnode>=0.9
metadata:
  owner: security
---

Follow this process:

1. Identify the host and timeframe.
2. Run the triage script for baseline indicators.
3. Summarize findings and next actions.

Discover and load skills

Use discoverSkills for a specific directory, or discoverAllSkills to search the default project paths and any extra paths (such as a capability’s bundled skills path).

import { discoverAllSkills, discoverSkills, createSkillTools } from '@dreadnode/agents';

async function main(): Promise<void> {
  const projectSkills = await discoverSkills('.skills');
  const allSkills = await discoverAllSkills(['./capabilities/threat-hunting/skills']);

  const skillTools = createSkillTools([...projectSkills, ...allSkills]);
  const toolNames = skillTools.map((tool) => tool.name);

  console.log(`Loaded ${skillTools.length} skill tools:`, toolNames.join(', '));
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Using skills in an agent

createSkillTools returns four tools (list_skills, load_skill, read_skill_file, run_skill_script) that you can merge into an agent’s tool map. Skills are loaded on-demand, so the agent only sees metadata until it requests full instructions.