Agent Skills

Updated on Oct 1, 2026

Skills are packages of instructions that AI agents load on demand. Forge uses them to tell agents how to work with your issue tracker, ticket tracker, code platform, and security scanner. Skills follow the Agent Skills standard and work with GitHub Copilot, Claude Code, and OpenCode.

Install skills

During initialization

frg config init installs only the skills required by tools that use method = "skill", which is the default for built-in tools:

bash

frg config init --issues github_issues --code github

This command exports issue-read-github and pr-read-github to .agents/skills/.

Export all built-in skills

bash

frg config export --skills

This command exports all 18 built-in skills. Existing skills are skipped unless you add --force. Custom skills are never generated; create them yourself.

Option	Description
`--skills`	Export built-in skill files to `.agents/skills/`
`--scope <SCOPE>`	`project` exports to `<repo>/.agents/skills/`. `user` exports to `~/.agents/skills/`.
`--force`	Overwrite existing files

Without --scope, Forge detects the scope from where it found your configuration: repository configuration (.forge/config/) uses project scope, and user configuration (~/.config/forge/) uses user scope.

bash

frg config export --skills --scope=user

Built-in skills

Tool type	Tool	Skills
Issue tracker	`github_issues`	`issue-read-github`
Issue tracker	`jira`	`issue-read-jira`
Issue tracker	`azure_devops`	`issue-read-azure-devops`
Issue tracker	`shortcut`	`issue-read-shortcut`
Code platform	`github`	`pr-read-github`
Code platform	`github_enterprise`	`pr-read-github-enterprise`
Code platform	`bitbucket`	`pr-read-bitbucket`
Code platform	`azure_devops`	`pr-read-azure-devops`
Ticket tracker	`github_issues`	`ticket-read-github`, `ticket-respond-github`
Ticket tracker	`jira`	`ticket-read-jira`, `ticket-respond-jira`
Ticket tracker	`azure_devops`	`ticket-read-azure-devops`, `ticket-respond-azure-devops`
Ticket tracker	`shortcut`	`ticket-read-shortcut`, `ticket-respond-shortcut`
Security scanner	`polaris`	`scanner-read-polaris`
Security scanner	`github_sast`	`scanner-read-github`

Tools that use method = "local" do not use skills.

Skill structure

text

skill-name/
├── SKILL.md # Required: frontmatter and instructions
└── references/ # Optional: detailed documents loaded on demand

SKILL.md starts with YAML frontmatter:

yaml

---
name: issue-read-github
description: >
 Retrieves and reads issues from GitHub using the gh CLI.
 Use when working with GitHub issues.
version: "1.0.0"
---

Field	Required	Description
`name`	Yes	Must match the directory name
`description`	Yes	What the skill does and when to use it
`version`	Yes	Version string that Forge compares during export

The body contains imperative instructions for the agent, for example commands such as gh issue list --state closed.

Customize a skill

Open .agents/skills/<skill-name>/SKILL.md.
Edit the body to match your team's practices, such as required labels or VPN access.
For long material, add files under references/ and point to them from SKILL.md, for example: "See references/jql-syntax.md for complex JQL patterns."
Commit the skill so your team shares it.

Create a skill for a custom tool

In toolchain.toml, set method = "skill" and, optionally, skill_name. Reference {{skill_name}} in the description:

toml

[issue_tracker]
name = "acme_tracker"
type = "custom"
method = "skill"
skill_name = "acme-issue-read"
description = "Use the {{skill_name}} skill to read ACME issues."

Create .agents/skills/acme-issue-read/SKILL.md.

Forge replaces {{skill_name}} with the skill name when it builds the prompt. If you omit skill_name, it defaults to the tool name.

Naming

Use lowercase kebab-case, for example acme-deploy-prod. The prefixes issue-, pr-, ticket-, and scanner- are reserved for built-in skills. Forge warns when a custom skill uses a reserved prefix.

Skill scope

Scope	Location	Use for
Project	`<repo>/.agents/skills/`	Team conventions, committed to version control
User	`~/.agents/skills/`	Personal skills available in all projects

The agent discovers skills from both locations. A project skill generally takes precedence over a user skill with the same name.

Update built-in skills

Forge does not update skills automatically, so your edits are preserved. When the version of an exported skill differs from the built-in version, frg config export --skills reports the differences. Example output (abbreviated):

text

Skill updates available:
 - issue-read-github: v1.0.0 → v1.1.0

Run 'frg config export --skills --force' to update

To update:

Back up your changes:

bash

cp -r .agents/skills/ .agents/skills-backup/

Overwrite the skills:

bash

frg config export --skills --force

Merge your customizations back from .agents/skills-backup/.

Forge only detects that the version strings differ. It does not check which version is newer.

Troubleshooting

The agent does not load a skill

Cause: The skill is in the wrong location or has invalid frontmatter.

Solution:

Confirm that the file is at .agents/skills/<skill-name>/SKILL.md.
Confirm that the frontmatter is valid YAML between --- lines.
Confirm that name matches the directory name exactly.

A skill update is not detected

Cause: The version field is missing or is not in the frontmatter.

Solution:

Add a non-empty version to the frontmatter.
Run frg config export --skills --force to replace the file.

The agent ignores a custom skill

Cause: The tool does not use the skill method, or the description does not name the skill.

Solution:

Set method = "skill" in toolchain.toml.
Set skill_name and reference {{skill_name}} in description.
Create .agents/skills/<skill_name>/SKILL.md. Forge does not export custom skills.