create-agent_skill

Overview

This skill creates and manages agent definitions for the code-forge application. It generates .md files placed in <cwd>/.forge/agents with required YAML frontmatter and a markdown body describing the agent's behavior and limits. Use it to add, update, or inspect agents so forge can discover and load them reliably.

How this skill works

The skill writes agent files named {agent-id}.md into the project-specific <cwd>/.forge/agents directory and validates required frontmatter fields: id, title, description, reasoning, tools, and user_prompt. It also helps compose the markdown body with identity, core principles, capabilities, methodology, best practices, and limitations. Forge only loads agents located exactly in that directory, so the skill enforces the file location and structure.

When to use it

• Add a new assistant with a specific purpose and tool set
• Modify an existing agent's behavior, tools, or prompts
• Audit or document the agent file structure for team members
• Create templates for research, planning, or implementation agents
• Ensure agents are discoverable by placing files in the correct directory

Best practices

• Use lowercase, hyphen-separated ids (e.g., code-reviewer) and clear titles
• Keep description concise (2–4 sentences) describing purpose, capabilities, and limits
• Select only the tools the agent needs to minimize scope and risk
• Enable reasoning only when the agent should perform multi-step inference
• Include the standard user_prompt block with event and system_date fields
• Place files only in <cwd>/.forge/agents so forge will discover them

Example use cases

• Create a read-only research agent (sage) that uses sem_search, read, and fetch
• Add an implementation agent (forge) that can read, write, patch, and run shell commands
• Compose a planning agent (muse) that outputs checklists and implementation steps
• Quickly scaffold a sample-agent.md to share agent conventions with the team
• Update an agent's tool list to add or remove permissions for actions