# Skillforge

> Create or update a reusable agent skill. Use when you notice a repeated pattern, when a workflow should be persisted for future sessions, or when asked to forge/create/scaffold a new skill.

- Skill: `zakelfassi/skillforge-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zakelfassi/skillforge-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zakelfassi/skillforge-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zakelfassi (https://skillmd.com/u/zakelfassi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zakelfassi/skillforge-2

---


# 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

```bash
mkdir -p .claude/skills/<skill-name>
```

(Or `.codex/skills/`, `.cursor/skills/`, `.github/skills/`, etc. — match the harness. In Claude Code this plugin targets `.claude/skills/`.)

### 4. Write SKILL.md

Use this skeleton:

```markdown
---
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>"
  status: active
---

# <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:

```
.claude/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` at the **project root** (same level as `.claude/`). Create it if it doesn't exist:

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

If the project uses the machine-readable registry (`.skills-registry.json`), update it too — the `skdd` CLI handles both formats automatically.

## Updating an Existing Skill

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

1. Add the new edge case or step to the existing SKILL.md
2. If the skill is getting too long (>200 lines), split it
3. 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 (plus trigger language like "Use when …")
- [ ] `name` matches the parent directory name
- [ ] 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`