When should I forge or update a skill?

Forge when you have repeated a sequence 2-3 times in a session, there is no documented project convention, you solved a hard problem with a reusable solution, or you are asked to create a skill. Do not forge for one time tasks, if an existing skill already covers it, or if the task is just a single command.

What should be included in a forged SKILL.md?

Include the name, description, inputs, steps, conventions, edge cases, and a clear purpose. Add optional scripts and references directories if needed, and register the skill in the registry.

skillforge

Scanned

npx machina-cli add skill zakelfassi/skills-driven-development/skillforge --openclaw

Files (1)

SKILL.md

2.7 KB

SkillForge

Create well-formed, spec-compliant skills from observed patterns.

When to Forge

✅ Forge when:

You've done the same sequence 2-3 times in a session
A project convention isn't documented anywhere
You solved a hard problem with a reusable solution
Someone asks you to create a skill

❌ Don't forge when:

It's a one-time task
An existing skill already covers it (update instead)
The "skill" is just a single command (use a script alias)

Steps

1. Name the pattern

What problem does this skill solve?
What triggers it? (be specific — the description field is the discovery surface)
What are the inputs and outputs?

2. Choose a name

kebab-case, 1-64 characters
Verb-led when possible: deploy-preview, scaffold-component, triage-bug
One responsibility per skill

3. Create the skill directory

mkdir -p .skills/<skill-name>

4. Write SKILL.md

Use this skeleton:

---
name: <skill-name>
description: <what it does>. Use when <triggers>.
metadata:
  forged-by: <agent-id>
  forged-from: <session-or-context>
  forged-reason: "<why this was created>"
---

# <Skill Name>

## Inputs
- ...

## Steps
1. ...
2. ...

## Conventions
- Project-specific patterns that apply

## Edge Cases
- Known gotchas or special handling

5. Add scripts (optional)

If the skill involves file generation or automation:

.skills/<skill-name>/
├── SKILL.md
├── scripts/
│   └── run.sh         # Executable automation
└── references/
    └── conventions.md # Detailed reference (keeps SKILL.md lean)

6. Register the skill

Update .skills-registry.md (create if it doesn't exist):

| <skill-name> | local | <today> | 1 | <description> |

Updating an Existing Skill

When you use a skill and encounter something it doesn't cover:

Add the new edge case or step to the existing SKILL.md
If the skill is getting too long (>200 lines), split it
Update last-used and increment usage-count in the registry

Quality Checklist

Before committing a new skill:

name is kebab-case, ≤64 chars
description includes what it does AND when to use it
Steps are numbered and actionable
No hardcoded paths, secrets, or environment-specific values
SKILL.md is under 200 lines (move details to references/)
Registered in .skills-registry.md

Source

git clone https://github.com/zakelfassi/skills-driven-development/blob/main/skillforge/SKILL.mdView on GitHub

Overview

SkillForge helps transform repeatable patterns into portable, spec compliant agent skills. By codifying triggers, inputs, outputs, and a SKILL.md skeleton, it makes patterns persistable and reusable across sessions. It also clarifies when to forge versus update existing work.

How This Skill Works

Identify a repeatable sequence and its triggers, then name it with kebab case and a verb lead. Create the skill directory under .skills, write a SKILL.md using the provided skeleton, and add optional scripts or references as needed. Finally register the skill in the skills registry to enable reuse.

When to Use It

You've repeated the same sequence 2-3 times in a session
There is no documented project convention for the task
You solved a hard problem with a reusable solution
You're asked to forge scaffold or create a new skill
You want to persist a workflow for future sessions

Quick Start

Step 1: Name the pattern - describe the problem and triggers
Step 2: Choose a name - use kebab-case and a verb led approach
Step 3: Create the skill directory with mkdir -p .skills/<skill-name> and write SKILL.md skeleton

Best Practices

Capture inputs, outputs, and triggers during the naming step
Use kebab-case for skill names and keep each skill focused on a single responsibility
Follow the SKILL.md skeleton and keep SKILL.md under 200 lines; move long details to references
Add optional scripts or references directories when automation or documentation is needed
Register the skill in .skills-registry.md with a concise description

Example Use Cases

A scaffold component pattern turned into a reusable skill after building several UI components
A triage bug pattern created after triaging multiple bugs in a session
A generate standard report pattern used across multiple projects
A setup ci pattern that initializes CI config in new repositories
A normalize logs pattern to standardize log formats across services

Frequently Asked Questions

Add this skill to your agents