Skills

Skills are markdown instructions that guide the agent's behavior for specific tasks or codebases. They can be provided inline, loaded from SKILL.md files on the virtual filesystem, auto-discovered from dot-directories, or activated conditionally based on file paths.

Auto-discovery

By default, the agent automatically discovers skills from .noumen/skills/ and .claude/skills/ in:

• Home scope: ~/.noumen/skills/, ~/.claude/skills/
• Project scope: every ancestor from the filesystem root down to cwd, e.g. <dir>/.noumen/skills/, <dir>/.claude/skills/

Each subdirectory containing a SKILL.md is loaded as one skill. Loose SKILL.md files at the dot-dir root (e.g. .noumen/SKILL.md) are ignored — skills must live under skills/, mirroring how rules/ works. Same-named skills are deduplicated with later (higher-precedence) scopes winning: project beats home, and within a scope the first name in dotDirs.names (default: .noumen) wins over the rest.

Auto-discovery is additive to skills and skillsPaths — explicit definitions still override discovered skills by name.

Narrow or rename the set of directories scanned via dotDirs:

const agent = new Agent({
  provider,
  sandbox,
  options: {
    // Only scan .noumen/skills/ (ignore .claude):
    dotDirs: { names: [".noumen"] },
  },
});

Inline skills

The simplest way to add skills is inline in the Agent options:

const code = new Agent({
  provider,
  sandbox,
  options: {
    skills: [
      {
        name: "Testing",
        content: "Always write vitest tests for new code. Use describe/it blocks.",
      },
      {
        name: "Style",
        content: "Use TypeScript strict mode. Prefer const over let.",
      },
    ],
  },
});

Loading from SKILL.md files

For larger skill definitions, use SKILL.md files on the virtual filesystem:

const code = new Agent({
  provider,
  sandbox,
  options: {
    skillsPaths: [".claude/skills", "~/.config/skills"],
  },
});

await code.init(); // loads SKILL.md files from the paths

Each SKILL.md file becomes a skill. The filename (minus extension) becomes the skill name, and the file contents become the skill instructions.

Frontmatter

SKILL.md files support YAML frontmatter for metadata:

---
description: Guidelines for writing API handlers
allowed-tools: ReadFile, WriteFile, EditFile
paths:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
context: inline
argument-hint: The specific handler to modify
---

When working on API handlers, follow these patterns:
- Use Zod for request validation
- Return consistent error shapes
- Add OpenAPI JSDoc comments

Frontmatter fields

Conditional activation

Skills with paths globs are only activated when the agent touches files matching those patterns. This keeps the system prompt focused and avoids injecting irrelevant instructions.

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

When writing tests, always:
- Use describe/it blocks
- Test both happy path and error cases
- Mock external dependencies

This skill only activates when the agent reads or edits test files.

The Skill tool

When skills are configured, a Skill tool is automatically added to the agent. The model can invoke skills by name:

Skill({ name: "Testing", arguments: "for the UserService class" })

The tool expands the skill content (substituting $ARGUMENTS with the provided arguments) and returns it to the model as a tool result.

SkillDefinition type

interface SkillDefinition {
  name: string;
  content: string;
  path?: string;
  description?: string;
  globs?: string[];
  allowedTools?: string[];
  context?: "inline" | "fork";
  argumentHint?: string;
}