Skip to content
Forge

Skills system

A skill is a markdown file that gets injected into the agent’s context when its triggers match. Skills give the agent persistent, opinionated guidance about specific topics: how to write idiomatic GDScript, how to structure a Unity scene, how to write a good Steam page.

Forge ships with a curated set of factory skills, and you can drop your own into the skills directory. The agent can also propose new skills for itself based on what it learns.

Where skills live

Section titled “Where skills live”
~/.forge/skills/
├── forge-self.md           Always-on, defines Forge's voice and conventions
├── windows-environment.md  Always-on, OS-specific guidance
├── unity.md
├── godot.md
├── threejs.md
├── ...                     Other factory skills
└── auto/                   Agent-generated skills
    └── <skill-name>/
        ├── v1.md
        ├── v2.md
        └── stats.json

Curated skills are flat markdown files. Auto-generated skills sit under auto/<name>/ with a versioned history and a stats sidecar.

Format

Section titled “Format”

A skill looks like this:

---
name: phaser-tilemaps
description: Phaser 3 tilemap setup, layers, and collision.
triggers:
  - phaser
  - tilemap
  - tile collision
engine: web
engine_version: ">=3"
version: "1.0"
always_on: false
---


# Tilemaps in Phaser 3


...body...

The frontmatter declares:

  • name: a unique slug.
  • description: one line, used in the manifest the agent always sees.
  • triggers: keywords. When your prompt or active file matches any trigger (case-insensitive), the skill body gets injected.
  • engine and engine_version: optional. Restricts the skill to projects matching that engine and version. Without them, the skill fires regardless of project type.
  • always_on: if true, the body is always injected. Used sparingly. forge-self and windows-environment are the two factory always-ons.

The body is markdown. Write it like you’d write a good Stack Overflow answer.

How matching works

Section titled “How matching works”

When you send a message that starts a fresh thread, Forge:

  1. Loads every skill in ~/.forge/skills/ and ~/.forge/skills/auto/.
  2. Filters out skills whose engine or engine_version doesn’t match your project.
  3. Filters out auto-skills with a success rate below 70% over 5 or more invocations.
  4. Matches the remaining skills’ triggers against your prompt and active file.
  5. Concatenates the bodies of matching skills into the developer instructions.

The full manifest of skill names (descriptions only, not bodies) is always included so the agent knows what’s available even if no triggers fire this turn.

Adding your own skills

Section titled “Adding your own skills”

Drop a markdown file into ~/.forge/skills/ with the frontmatter above. Forge picks it up immediately. No restart needed.

The factory pack is checked into Forge and copied into ~/.forge/skills/ on first launch (or when their version: bumps). If you edit a factory skill in place, your edits stick around until the version bumps, then your edits get overwritten. To make permanent changes, rename the file or fork it under a new name.

Auto-skills

Section titled “Auto-skills”

When the agent learns something useful (a workaround, a pattern, a project-specific convention), it can propose a new skill. The proposal arrives in chat as a card with the proposed frontmatter and body. Approve it and the skill lands in ~/.forge/skills/auto/<name>/v1.md and is loadable from the next turn.

Auto-skills track their own usage. Each invocation increments invocations; a successful turn (where the agent’s output didn’t get rejected) increments successes. The skill’s success rate is the ratio.

The Settings → Skills panel shows two lists, curated and auto. Auto-skills have extra affordances:

  • View history: scroll back through previous versions.
  • Promote: move the skill from auto/<name>/v<n>.md into the flat ~/.forge/skills/<name>.md namespace. Once promoted, it’s treated as curated.
  • Delete: remove it entirely.

View history lists every version on disk. Pick an earlier one to revert to. The promotion and deletion happen against the latest version.

Auto-deprecation

Section titled “Auto-deprecation”

Auto-skills with a success rate below 70% over 5 or more invocations are considered stale. They’re still on disk, but Forge filters them out at trigger-matching time so they don’t poison new turns. You can promote them, delete them, or leave them dormant.

This is the safety net for skills the agent proposed but turned out to be wrong. Without it, bad skills would compound.