# Where Are CyberStrikeAI Role, Skill, and Tool Definitions Stored?

> Discover where CyberStrikeAI stores role, skill, and tool definitions. Find these crucial configuration files in the roles skills and tools directories within the Ed1s0nZ/CyberStrikeAI repository.

- Repository: [公明/CyberStrikeAI](https://github.com/Ed1s0nZ/CyberStrikeAI)
- Tags: internals
- Published: 2026-03-09

---

**CyberStrikeAI stores its role, skill, and tool definitions in plain-text YAML and Markdown files within the `roles/`, `skills/`, and `tools/` directories of the repository.**

The open-source CyberStrikeAI framework (available at `Ed1s0nZ/CyberStrikeAI`) uses a declarative configuration system that keeps AI agent configurations transparent and version-controlled. Unlike hardcoded definitions, the project separates behavioral logic into readable files that the backend loads dynamically at runtime.

## Role Definitions in the `roles/` Directory

CyberStrikeAI roles are defined as individual **YAML** files inside the `roles/` folder. Each file represents a distinct agent persona that the UI presents in the role selector. According to the source code, the backend exposes these via the `/api/roles` endpoint, while the front-end renders them through [`web/static/js/roles.js`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/web/static/js/roles.js).

A role definition specifies:
- **name**: Display name (e.g., "默认" for Default)
- **description**: Human-readable summary of the role's purpose
- **icon**: Unicode emoji or icon string for the UI
- **enabled**: Boolean flag controlling availability
- **tools** and **skills**: Optional lists restricting which capabilities the role may use (omitted means all enabled tools are available)

```yaml

# roles/默认.yaml

name: 默认
description: 默认角色，不额外携带用户提示词，使用默认MCP
user_prompt: ""
icon: "\U0001F535"
enabled: true

# tools and skills omitted → role uses all enabled tools by default

```

## Skill Definitions in the `skills/` Directory

Skills reside in the `skills/` directory following a strict convention: each skill occupies its own subdirectory containing a [`SKILL.md`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/SKILL.md) file. The system locates these files via the `skills_dir` parameter in [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) (lines 163‑165), defaulting to the `skills/` folder.

The **Markdown** format allows rich documentation including objectives, usage instructions, and prompt templates. For example, [`skills/sql-injection-testing/SKILL.md`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/skills/sql-injection-testing/SKILL.md) contains the human-readable description that guides the AI when executing security tests.

```markdown
<!-- skills/sql-injection-testing/SKILL.md -->

# SQL 注入测试

## 目标

检测 Web 应用是否存在 SQL 注入漏洞。

## 使用方法

1. 在聊天中输入 “进行 SQL 注入测试”。
2. 系统会自动运行 `sqlmap` 并返回结果。

```

## Tool Definitions in the `tools/` Directory

Tool manifests are stored as individual **YAML** files in the `tools/` directory. These files declare executable security utilities that roles can invoke. The backend serves these definitions through the `/api/config/tools` endpoint, which the role management interface consumes to populate tool selection checkboxes.

Each tool specification includes:
- **name**: Command identifier
- **description**: Purpose explanation
- **command**: Execution string with placeholders like `{target}`
- **tags**: Categorization labels (e.g., `network`, `scanning`)
- **external**: Boolean indicating MCP (Model Context Protocol) integration status

```yaml

# tools/nmap.yaml

name: nmap
description: 网络扫描工具，用于发现开放端口和服务
command: nmap -sV -p {ports} {target}
tags:
  - network
  - scanning
external: false

```

## Configuration Loading Mechanism

The system initializes by reading [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) to determine the `skills_dir` location. At startup, the backend recursively scans these directories, parsing YAML role definitions and Markdown skill documentation into memory. This design allows hot-reloading configurations without recompiling the application, as the file-based storage enables immediate updates by editing plain text.

## Summary

- **Roles**: Stored as `*.yaml` files in `roles/` – define agent personas, icons, and capability lists
- **Skills**: Stored as [`SKILL.md`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/SKILL.md) files in `skills/<skill-name>/` subdirectories – contain human-readable descriptions and usage instructions
- **Tools**: Stored as `*.yaml` files in `tools/` – declare executable commands, arguments, and metadata
- **Configuration**: [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) (lines 163‑165) sets the `skills_dir` path, while `/api/roles` and `/api/config/tools` serve the data to the frontend

## Frequently Asked Questions

### What file format does CyberStrikeAI use for role definitions?

CyberStrikeAI uses **YAML** files stored in the `roles/` directory. Each role has its own `.yaml` file containing the name, description, icon, enabled status, and optional tool/skill assignments.

### How does CyberStrikeAI locate skill documentation?

The framework reads the `skills_dir` value from [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) (defaulting to `skills/`) and dynamically loads all [`SKILL.md`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/SKILL.md) files found in subdirectories. Each skill must follow the `skills/<skill-name>/SKILL.md` convention.

### Can tool definitions reference external MCP servers?

Yes. Tool YAML files include an `external` boolean field. When set to `true`, the tool connects to an external Model Context Protocol (MCP) server rather than executing a local command.

### Where is the endpoint that serves role configurations to the frontend?

The backend exposes role data via the `/api/roles` endpoint, which [`web/static/js/roles.js`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/web/static/js/roles.js) consumes to render the role selection interface in the web UI.