This guide explains how to configure skills and dynamic workflows for agents in the Fuchsia project.
The Fuchsia project maintains agents' global skills in //.agents/skills and saved dynamic workflows in //.agents/workflows in fuchsia.git. You can also manage your own skill configurations using skills.json files.
As you add a new skill to the Fuchsia codebase, follow these guidelines:
fuchsia.git (e.g. a team subdirectory) so that others can discover and use it.fuchsia.git) users by putting it in the global registry.Note: If your skill is only useful to a small group of Fuchsia developers, it does not need to be a global skill in the Fuchsia codebase.
Use this stage when a skill works reliably and you want to share it with your sub-team or group of teammates.
Add your skill to a directory or sub-directory in the fuchsia.git repository outside of the top-level //.agents/skills/ directory (for example, //src/devices/skills/).
Keep in mind that agents do not automatically discover skills outside the top-level //.agents/skills directory in fuchsia.git. Other Fuchsia workspace users need to configure their skills.json files to discover and use these skills. See Skill discovery and configuration.
Use this stage when a skill works reliably and is useful to most of the Fuchsia team.
fuchsia.git repository in //.agents/skills/.OWNER listed in the //.agents/ OWNERS file.Agents use JSON configuration files (skills.json) to discover custom skills.
The agent reads skills.json from these paths (loaded in order):
~/.gemini/config/skills.json - Personal skill configuration active globally across workspaces on your machine..agents/skills.json - Repository-managed project-wide default skills for this Fuchsia workspace. Do not edit this file for personal customizations.When loading large skill repositories or team configurations, avoid having every single skill active at once. Create a skills.json (such as ~/.gemini/config/skills.json) that includes skills using inherits and entries.
inherits: Imports another entire JSON configuration file. Use this for importing a standard team config.entries: Points directly to a directory containing a single skill.Both keys support include_only and exclude filters (string arrays) to selectively parse skills.
{ "inherits": [ { "path": "/path/to/fuchsia/docs/team_skills.json", "include_only": ["cpp-to-rust-porting"] } ], "entries": [ { "path": "/path/to/fuchsia/src/devices/skills/custom_sensor_skill" } ] }
The fx manage-skills tool provides an interactive command-line interface for creating and editing your personal global skills.json file (at ~/.gemini/config/skills.json).
Run the following command in your shell:
fx manage-skills
This command scans the workspace, displays all discovered skills, and prompts you to select the ones you want to enable. It automatically generates or updates ~/.gemini/config/skills.json with your selections.
The fx manage-skills tool also supports a non-interactive mode for scripting and quick updates using command-line flags:
--add=<path>: Adds a skill or container path to your configuration. If the path points to a single skill (containing SKILL.md), it is added without recursive inclusion. If it is a container directory, it is added with recursive inclusion.--remove=<path>: Removes any entries in ~/.gemini/config/skills.json whose path matches or begins with the specified path.--migrate: Migrates any existing custom entries from workspace .agents/skills.json to ~/.gemini/config/skills.json and cleans up the workspace file.--list: Displays the current contents of ~/.gemini/config/skills.json.--clear: Removes all entries from ~/.gemini/config/skills.json.For example, to add multiple skill paths and list the resulting configuration:
fx manage-skills --add=//src/devices/skills --add=//docs/skills fx manage-skills --list
//.agents/workflows/)A dynamic workflow is a saved Python orchestration script executed by the run_workflow tool that coordinates multiple child agents and tool calls across sequential or parallel phases (phase, parallel, pipeline, agent, and call_tool). For full documentation on authoring and running dynamic workflows, see go/jetski-workflows.
Saved workflows live under //.agents/workflows/<workflow-name>/ and contain:
workflow.json: The workflow manifest defining name, description, entry (defaults to workflow.py), and an optional args JSON Schema that validates input arguments before execution.workflow.py: The Python script that orchestrates child agents, each returning a JSON Schema-validated result in its own isolated conversation.Workflows under //.agents/workflows/<workflow-name>/ are automatically discovered and exposed as /<workflow-name> slash commands (for example, /evaluate-review-skills).
SKILL.md) when you want to teach an agent domain knowledge, coding or code-review rubrics, or interactive tool procedures:/review (via AGENTIC_REVIEW) or Gerrit AI review (CRACS).fx test, fx gh, or debugger commands) and interactive triage runbooks where a single agent reasons step-by-step in the main conversation./<skill-name>.workflow.json + workflow.py) when the orchestration control flow itself should be deterministic Python code:parallel): Auditing or transforming many files, packages, or skills concurrently using isolated child agents without bloating the main conversation's context window.pipeline) and verification loops: Chaining deterministic phases (for example, Discover $\rightarrow$ Evaluate in Parallel $\rightarrow$ Adversarial Audit $\rightarrow$ Report) where every child agent must return structured JSON matching a strict schema.