@samitouri / QOSami_Agents_Zero-1
Code Commits Issues Pulls Sessions CI/CD
main
main
md 4.56 KB
View source Raw

Agents, Prompts, Skills, And Projects

Source Anchors

  • Agent profiles: /a0/helpers/subagents.py, /a0/agents/AGENTS.md
  • Prompt rendering: /a0/agent.py, /a0/helpers/files.py, /a0/prompts/AGENTS.md
  • Skill runtime: /a0/helpers/skills.py, /a0/tools/skills_tool.py, /a0/skills/AGENTS.md
  • Project metadata: /a0/helpers/projects.py, /a0/api/projects.py, /a0/webui/components/projects/

Agent Profiles

Bundled profiles live under agents/<profile>/. User-created profiles live under usr/agents/<profile>/. Plugin-distributed profiles live under plugin agents/ directories.

The current profile loader accepts agent.yaml or agent.json and validates through helpers.subagents.SubAgentListItem / SubAgent fields:

Field Meaning
title Human-readable display name. Defaults to profile name if empty.
description Brief specialization.
context Delegation guidance for when to use the profile.
enabled Optional availability flag in list contexts.

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.

Profile folders may contain prompts/, tools/, extensions/, and skills/, but verify discovery code before relying on example layout. Source and DOX beat stale examples.

Prompt System

Agents render prompt fragments through Agent.read_prompt(...), which calls helpers.files.read_prompt_file(...).

Prompt capabilities:

  • Placeholder replacement with {{variable_name}}.
  • Conditional blocks with {{if ...}} ... {{endif}}.
  • Include directives such as {{include "file.md"}}.
  • {{include original}} to include the same file from a lower-priority directory.

Prompt locations include:

Location Use
prompts/ Core framework prompts.
agents/<profile>/prompts/ Bundled profile overrides.
usr/agents/<profile>/prompts/ User profile overrides.
plugins/<plugin>/prompts/ Bundled plugin prompt additions or overrides.
usr/plugins/<plugin>/prompts/ User plugin prompts.

Prompt changes can change agent behavior. Keep edits narrow and run targeted prompt, budget, snapshot, tool, or behavior tests.

Skills

Skills are directories containing SKILL.md frontmatter plus optional references/, scripts/, or assets/.

Skill roots come from helpers.skills.get_skill_roots(...), including bundled skills, user skills, project metadata, profile skills, and plugin skills.

skills_tool actions:

Action Purpose
list List available skills without full content.
search Search skill metadata and triggers.
load Load SKILL.md body and show the skill file tree.
read_file Read a file inside the skill directory, such as references/foo.md.

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.

Use build-skill for skill creation and skill format work.

Projects

Projects live under usr/projects/<name>/ and store metadata in .a0proj/.

Important project files and folders:

Path Purpose
.a0proj/project.json Project title, description, instructions, color, git URL, include-AGENTS option, and file-structure settings.
.a0proj/instructions/ Additional text instruction files.
.a0proj/knowledge/ Project knowledge files.
.a0proj/variables.env Non-sensitive project variables.
.a0proj/secrets.env Encrypted project secrets.
.a0proj/agents/ Per-project agent profile material.
.a0proj/skills/ Project-scoped skills.
.a0proj/mcp_servers.json Project MCP server configuration.

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.

Project file-structure injection uses settings for enabled, max_depth, max_files, max_folders, max_lines, and gitignore.

Verification

  • Run profile-loading tests when changing agent profile schema or discovery.
  • Inspect rendered prompts when changing prompt filenames, include behavior, placeholders, or prompt order.
  • Run skill runtime/catalog tests after changing skill loading, search, active/hidden behavior, or skill format.
  • For project changes, test create/load/edit paths and project prompt injection when relevant.