| 1 | # Agents, Prompts, Skills, And Projects |
| 2 | |
| 3 | ## Source Anchors |
| 4 | |
| 5 | - Agent profiles: `/a0/helpers/subagents.py`, `/a0/agents/AGENTS.md` |
| 6 | - Prompt rendering: `/a0/agent.py`, `/a0/helpers/files.py`, `/a0/prompts/AGENTS.md` |
| 7 | - Skill runtime: `/a0/helpers/skills.py`, `/a0/tools/skills_tool.py`, `/a0/skills/AGENTS.md` |
| 8 | - Project metadata: `/a0/helpers/projects.py`, `/a0/api/projects.py`, `/a0/webui/components/projects/` |
| 9 | |
| 10 | ## Agent Profiles |
| 11 | |
| 12 | Bundled profiles live under `agents/<profile>/`. User-created profiles live under `usr/agents/<profile>/`. Plugin-distributed profiles live under plugin `agents/` directories. |
| 13 | |
| 14 | The current profile loader accepts `agent.yaml` or `agent.json` and validates through `helpers.subagents.SubAgentListItem` / `SubAgent` fields: |
| 15 | |
| 16 | | Field | Meaning | |
| 17 | |---|---| |
| 18 | | `title` | Human-readable display name. Defaults to profile name if empty. | |
| 19 | | `description` | Brief specialization. | |
| 20 | | `context` | Delegation guidance for when to use the profile. | |
| 21 | | `enabled` | Optional availability flag in list contexts. | |
| 22 | |
| 23 | Bundled `agent.yaml` files currently use `title`, `description`, and `context`. Model settings are not read from `agent.yaml`; the `_model_config` plugin owns model configuration and scoped overrides. |
| 24 | |
| 25 | Profile folders may contain `prompts/`, `tools/`, `extensions/`, and `skills/`, but verify discovery code before relying on example layout. Source and DOX beat stale examples. |
| 26 | |
| 27 | ## Prompt System |
| 28 | |
| 29 | Agents render prompt fragments through `Agent.read_prompt(...)`, which calls `helpers.files.read_prompt_file(...)`. |
| 30 | |
| 31 | Prompt capabilities: |
| 32 | |
| 33 | - Placeholder replacement with `{{variable_name}}`. |
| 34 | - Conditional blocks with `{{if ...}} ... {{endif}}`. |
| 35 | - Include directives such as `{{include "file.md"}}`. |
| 36 | - `{{include original}}` to include the same file from a lower-priority directory. |
| 37 | |
| 38 | Prompt locations include: |
| 39 | |
| 40 | | Location | Use | |
| 41 | |---|---| |
| 42 | | `prompts/` | Core framework prompts. | |
| 43 | | `agents/<profile>/prompts/` | Bundled profile overrides. | |
| 44 | | `usr/agents/<profile>/prompts/` | User profile overrides. | |
| 45 | | `plugins/<plugin>/prompts/` | Bundled plugin prompt additions or overrides. | |
| 46 | | `usr/plugins/<plugin>/prompts/` | User plugin prompts. | |
| 47 | |
| 48 | Prompt changes can change agent behavior. Keep edits narrow and run targeted prompt, budget, snapshot, tool, or behavior tests. |
| 49 | |
| 50 | ## Skills |
| 51 | |
| 52 | Skills are directories containing `SKILL.md` frontmatter plus optional `references/`, `scripts/`, or `assets/`. |
| 53 | |
| 54 | Skill roots come from `helpers.skills.get_skill_roots(...)`, including bundled skills, user skills, project metadata, profile skills, and plugin skills. |
| 55 | |
| 56 | `skills_tool` actions: |
| 57 | |
| 58 | | Action | Purpose | |
| 59 | |---|---| |
| 60 | | `list` | List available skills without full content. | |
| 61 | | `search` | Search skill metadata and triggers. | |
| 62 | | `load` | Load `SKILL.md` body and show the skill file tree. | |
| 63 | | `read_file` | Read a file inside the skill directory, such as `references/foo.md`. | |
| 64 | |
| 65 | Keep always-loaded `SKILL.md` concise. Move long examples, schemas, policies, and variant-specific details into one-level-deep `references/` files and tell the agent when to read them. |
| 66 | |
| 67 | Use `build-skill` for skill creation and skill format work. |
| 68 | |
| 69 | ## Projects |
| 70 | |
| 71 | Projects live under `usr/projects/<name>/` and store metadata in `.a0proj/`. |
| 72 | |
| 73 | Important project files and folders: |
| 74 | |
| 75 | | Path | Purpose | |
| 76 | |---|---| |
| 77 | | `.a0proj/project.json` | Project title, description, instructions, color, git URL, include-AGENTS option, and file-structure settings. | |
| 78 | | `.a0proj/instructions/` | Additional text instruction files. | |
| 79 | | `.a0proj/knowledge/` | Project knowledge files. | |
| 80 | | `.a0proj/variables.env` | Non-sensitive project variables. | |
| 81 | | `.a0proj/secrets.env` | Encrypted project secrets. | |
| 82 | | `.a0proj/agents/` | Per-project agent profile material. | |
| 83 | | `.a0proj/skills/` | Project-scoped skills. | |
| 84 | | `.a0proj/mcp_servers.json` | Project MCP server configuration. | |
| 85 | |
| 86 | `helpers.projects.BasicProjectData` currently normalizes `title`, `description`, `instructions`, `include_agents_md`, `color`, `git_url`, and `file_structure`. `EditProjectData` adds runtime/editing fields such as `variables`, `secrets`, `mcp_servers`, `subagents`, and git status. |
| 87 | |
| 88 | Project file-structure injection uses settings for `enabled`, `max_depth`, `max_files`, `max_folders`, `max_lines`, and `gitignore`. |
| 89 | |
| 90 | ## Verification |
| 91 | |
| 92 | - Run profile-loading tests when changing agent profile schema or discovery. |
| 93 | - Inspect rendered prompts when changing prompt filenames, include behavior, placeholders, or prompt order. |
| 94 | - Run skill runtime/catalog tests after changing skill loading, search, active/hidden behavior, or skill format. |
| 95 | - For project changes, test create/load/edit paths and project prompt injection when relevant. |