Create Skill

When to Use

Creating a new skill for Forge, a department, or a project.

Location

Scope	Path
Cross-cutting / Forge-level	Forge/Skills/{Skill_Name}/SKILL.md
Department-specific	{Dept}/Skills/{Skill_Name}/SKILL.md
Function-specific	{Dept}/{Function}/Skills/{Skill_Name}/SKILL.md

Choose the narrowest scope that fits. If only one function uses it, it’s a function skill.

Structure

Skill_Name/
├── SKILL.md                # Procedure outline (≤ 500 words)
├── do-thing.ts             # Executable logic written in TypeScript (or legacy Python) (optional)
├── skill-name-config.yaml  # Skill configuration (optional)
├── skill-name-state.json   # Persistent skill state (optional)
└── references/             # Deep reference material (optional)
    └── detailed-spec.md

SKILL.md Template

---
name: kebab-case-name
description: Use when [trigger condition]
title: "Human Title"
visibility: internal
status: published
owner: "erik@uvilo.com"
tags: [relevant, tags]
---

# Human Title

## When to Use
[One-liner trigger condition]

## Prerequisites
- [Dependency, tool, access, env var, or precondition that must already exist]
- [If none, say "None"]

## Procedure
[Numbered steps — what to do, not how the world works]

## Rules
[Hard constraints, if any]

Authoring Rules

1. Action-oriented naming. Name the skill in the format {Verb} {Noun}. For example “Create Skill”, “Reindex Typesense”
2. ≤ 500 words. SKILL.md is loaded into context per-session — every word costs tokens. Put only the procedure outline and essential constraints here.
3. Scripts over prose. Any logic that can be implemented in TypeScript or a Bash script MUST be a script, not agent instructions. The SKILL.md just says “run the script” and documents its inputs/outputs.
4. TypeScript only. No Python, no plain JS. Choose the pattern per the Write Typescript skill — bundled project (MCP servers, long-running services) or standalone script (skill utilities, npx tsx script.ts).
5. Declare prerequisites explicitly. Every SKILL.md must include a ## Prerequisites section listing required tools, dependencies, access, env vars, and assumptions that must already exist. If there are no prerequisites, write None.
6. Preconfigured by default. A skill’s prerequisites are assumed to be preconfigured. Do not design skills that silently install or repair their own dependencies unless setup is explicitly part of the skill.
7. References for depth. Detailed specs, examples, or lookup tables go in References/ — never inline them in SKILL.md.
8. Self-contained definitions. Don’t reference undefined concepts. A reader should understand the skill without chasing cross-references.
9. Compress over enumerate. If items follow a repeatable pattern, state the pattern rule once. If the same information appears in two forms, keep only the denser one.
10. One skill, one concern. If the procedure has two unrelated workflows, split into two skills.
11. No hardcoded values. Never hardcode hosts, API keys, ports, or collection names in scripts or SKILL.md examples. Always read from environment variables. Use the idiomatic env var access for the language you’re writing in. Fail loudly if a required env var is missing.

Procedure

1. Determine scope → pick location (Forge / department / function)
2. Create folder and SKILL.md from template, including an explicit ## Prerequisites section
3. If the skill has executable logic, write it as a TypeScript script
4. Ensure the listed prerequisites match the actual implementation and environment assumptions
5. Add skill name to the Available Skills list in the Persistent Knowledge database prompt (where the Available Skills list resides)
6. Spawn the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' } to list all the files in the sidebar
7. Build: cd .internal && npm run build
8. Commit all files together and push to origin
9. Remind user to run Update Agents to sync the skill list to bots