How to use the Create Forge Agents agent skill (create-agent)

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that gives an AI assistant extra instructions for a specific task. This skill covers one task: creating and editing agents for the code-forge application.

Agents in code-forge are stored as markdown files. Each file has YAML frontmatter with the fields id, title, description, reasoning, tools and user_prompt, followed by a markdown body with the agent's instructions. When the skill is active, the agent knows this structure and the naming convention, so forge can discover and load the new agent.

• It knows the required frontmatter fields and the body sections to include.
• It places files in the correct folder and names them consistently.
• It does not add any new tools or capabilities to the agent itself.

Install the create-agent skill

Download the create-agent ZIP from this page. The package contains one file, SKILL.md. Install it in one of these ways.

For a personal install that applies to all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Where agent files must go

Every custom agent must be saved in <cwd>/.forge/agents, where <cwd> is the working directory of your code-forge project. The file name is {agent-id}.md. The source states that this is the only location where forge will discover and load custom agents, so a file saved anywhere else will be ignored.

• Directory: <cwd>/.forge/agents
• File name: {agent-id}.md, for example code-reviewer.md
• Example: a project at /home/user/my-project stores agents in /home/user/my-project/.forge/agents/

Ask for an agent with a natural request

Once the skill is installed, describe the agent you want in plain language. The skill is meant to be used when you need to add a new agent, modify an existing one, or understand the agent file structure.

Give the agent a purpose, the tasks it should handle, the tools it needs and its limits. The source recommends choosing tools by purpose: implementation agents usually use read, write, patch, shell, sem_search and fs_search, while research agents use sem_search, search, read, fetch and sage.

• "Create a code-forge agent called test-automation that writes and runs unit tests. It should use read, write, patch, shell and sem_search."
• "Add a code-forge agent for reviewing pull requests. It is read-only, so give it read, sem_search and fetch."
• "Show me the file structure for a code-forge agent and update my existing reviewer agent's description."

Check the generated agent file

Open the file the agent creates and confirm it matches the required structure: frontmatter with id, title, description, reasoning with enabled set to true or false, tools as a list, and a user_prompt block. The skill does not verify that an agent is safe or well-behaved, so read the tools list and the instructions yourself before relying on the agent.

Check the id and file name match, and that the file sits in <cwd>/.forge/agents.

• Frontmatter fields are all present.
• File name matches the id value.
• Tools list contains only what the agent needs.
• The body covers identity, principles, capabilities, methodology, best practices and limits.

Safety notes

According to the skill's listing, it runs no scripts and uses no network access. It only guides how the agent writes files. The tools you assign to a custom agent determine what that agent can do once forge loads it, for example shell gives it the ability to run shell commands.

Review each new agent's tools list before use, especially if it includes shell, write, remove or wildcard entries such as mcp_*.

• Scripts: none included
• Network: none used by the skill
• Permissions come from the tools list you approve in the agent file