# ocas-forge

Adopt this skill: https://proskills.md/skills/software-development/indigokarasu-forge

Page: https://proskills.md/skills/software-development/indigokarasu-forge
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8095
upstream: https://github.com/indigokarasu/forge/blob/HEAD/SKILL.md

```text
---
warning: 'FALSE TRIGGER RISK: rate CORRECTED 2026-09-26 from 100% (2/3) to NOT-MEASURED. All 3 interactive loads were user_prompted=true, i.e. explicitly requested, so an interactive false-trigger rate is not meaningful for this skill. The prior 100% also carried a miner bug that attributed the next 10 messages'' tools to every skill loaded in the same burst. Do not treat this skill as excluded — it is safe to load on request.'
name: ocas-forge
description: 'Skill architect and builder. Designs, builds, and validates complete Agent Skill packages through a mandatory eight-phase pipeline. Default output is the finished installable package. Not for skill evaluation (use skilllab) or variant proposals (use ocas-mentor).'
license: MIT
source: https://github.com/indigokarasu/forge
includes:
- references/**
- scripts/**
metadata:
  author: Indigo Karasu (indigokarasu)
  version: "3.8.0"
  hermes:
    category: software-development
    tags:
    - skill-builder
    - architecture
    - design
    - OCAS-core
tags:
- skill-builder
- architecture
- design
- OCAS-core
triggers:
- build a skill
- create skill
- skill architecture
- design skill package
- skill builder
---

# Occas-Forge

Skill architect and builder. Given a capability idea or broken package, runs a mandatory eight-phase pipeline before writing files. Default output is the finished installable package — never returns design briefs or plans in place of real artifacts.

Every build starts with absorption check, research, and classification before a single file is created.

**Support files:** `references/support-file-map.md` indexes the bundled files not covered inline in this skill — check it before working from assumptions about what is (not) available.

## Why This Skill Exists

Forge is the only authorized skill builder in OCAS. Without it, agents would create skills with inconsistent structure, missing frontmatter, no tests, and no cross-skill coordination. The rigid pipeline ensures every skill meets OCAS standards and doesn't duplicate existing work.

## When to Use

- Building new OCAS skills from scratch
- Skill architecture and design review
- Bulk skill library updates and synchronization
- Skill consolidation and deprecation
- Repair broken or defective skill packages
- Validate a skill package against OCAS standards

## When NOT to Use

- **Skill evaluation/scoring** — use skilllab
- **Variant proposals/experiments** — use Mentor or Fellow
- **System health monitoring** — use Custodian
- **One-off task execution** — use the appropriate existing skill
- **Web research** — use Sift
- **Authentication and MCP wiring** — use ocas-auth
- **Frontmatter reference/template lookup** — use `write-a-skill` for quick field requirements
- **Building non-skill artifacts**

## Pipeline

- [ ] **Existence gate** — check if skill already exists, absorption test
- [ ] **Research** — search GitHub + skill library for patterns; review ≥10 sources
- [ ] **Classify** — determine shortcut/workflow/system type
- [ ] **Scope** — define boundaries and interfaces
- [ ] **Architecture** — design package structure
- [ ] **Plan** — create implementation plan
- [ ] **Build** — implement the skill
- [ ] **Validate** — run critique and verify 50/50

**Absorption first:** If an existing skill already owns the domain, add content as a `references/` doc or `scripts/` file — do NOT create a new skill. See `references/enforcement_durability.md`.

**Research is mandatory for ALL operations** — not just new builds. When improving an existing skill, you MUST research external sources for new patterns.

**Pre-Build Quality Linters** (embedded in the Validate step, per [[`spec-ocas-skill-improvements.md` ⚠️ Pending spec] ⚠️ Pending spec — not yet authored] §5.1):
1. **Frontmatter verification** — validate required metadata fields (`name`, `description`, `version`, `author`).
2. **Incident-log shape detection** — flag skill descriptions / reference bodies overly dense in ephemeral issue numbers or quoted chat transcripts instead of generalizable rules.
3. **Reference sprawl check** — fail the build if `references/` exceeds 60 files.
4. **Config vs env separation** — reject scripts that read behavioral configuration from `os.environ` instead of `skills.config.<key>` in `config.yaml` (reserving env vars strictly for credentials/secrets).
Run all four before a new package is marked valid; a failing linter blocks promotion to production.

## Commands

- `forge.build` — design, scope, build, validate a complete skill package
- `forge.critique` — review package and identify defects
- `forge.repair` — fix broken files in existing package
- `forge.validate` — run validation checks on a package
- `forge.audit` — audit one or more skills for OCAS compliance, apply fixes, sync to GitHub
- `forge.consolidate` — merge orphan/duplicate skill into natural parent
- `forge.sync` — sync local changes to canonical repository via PR
- `forge.update` — pull latest from GitHub source
- `forge.status` — current build state (multi-step)
- `forge.journal` — write journal for current run

**Run completion:** After every command, check for unprocessed VariantProposal/VariantDecision files in `intake/`, process new files, persist build logs to `decisions.jsonl`, write journal. Never report success until validation has actually executed — `write_file`/`skill_manage(action='create')` completing is NOT validation.

## Triage Classification (dispatch)

| Intent | Priority | Action | When |
|--------|----------|--------|------|
| new_journals | 50 | dispatch_scan | Files need eval-store bridge |
| explicit_run | 80 | run_full_pipeline | Explicit-run override detected |
| re_detection | 30 | closure_noop | All journals already in both eval stores |

## Skill Type Classification

- **Shortcut** — narrow tool wrapper. 20-120 line SKILL.md.
- **Workflow** — multi-step process. 80-250 line SKILL.md.
- **System** — durable behavior system. 150-300 line SKILL.md + references.

## Error Handling

| Error | Handling |
|-------|----------|
| `closure_closeout_check.py` gate [1] reads `dispatch=False` although your audit found the journal bridged in both stores | `in_store()` (line ~54) is a raw substring grep for the **full relpath** in BOTH `ocas-praxis` and `ocas-dispatch` `journals_evaluated.jsonl`. An entry carrying only `filename: <bare>.json` matches Step 2 / human greps but NOT gate [1]. Emit both keys in the dispatch entry: `filename` (bare) and `journal_id` (`ocas-<skill>/<date>/<file>.json`). Do not trust a `GAPS=0` from a basename-matched audit — audit with the reader's own semantics. |
| `closure_closeout_check.py` reports `[2] monitor ROOT ... : False (MISSING ...)` while `advance_gate_state.py` wrote a real file | The checker's `MON_STATE_ROOT` is derived via `HERMES_HOME.replace("/profiles/indigo", "/commons/data/...")`. When `HERMES_HOME=/root/.hermes` (no `/profiles/indigo` segment) the replace is a no-op and the path resolves to a nonexistent file, so the gate reads MISSING even though the real monitor copy is advanced. Do NOT re-advance and do NOT report STALE. Re-run with `HERMES_HOME=/root/.hermes/profiles/indigo` so the replace matches and the check reads the file that was actually written. Requires `=== gates ALL CLOSED ===`. |
| `closure_closeout_check.py` crashes (FileNotFoundError – `<hermes-home>` placeholder) | Skip script. Manually verify gates: (1) grep bare relpath in both eval stores, (2) recompute max journal mtime programmatically + ≥2s pad, advance both monitor copies + praxis `ingest_state.json`, (3) re-assert `verified_second_wave` on all dispatch-owned files. |
| `run_mixed_wave_closure.py` crashes (NameError: 'os') | Handle closure manually. Same manual procedure as above. |
| `bridge_eval_inline.py` crashes (FileNotFoundError) | Manual JSONL append to both eval stores. |
| `forge_count_unprocessed.py` returns 0 but dispatcher says genuine | Cross-check against prior `forge-scan-*.json` journal's `unprocessed_proposals` field
```

## File: README.md
upstream: https://github.com/indigokarasu/forge/blob/HEAD/README.md

```text
# Forge

  <img src="./assets/readme/hero.jpg" width="100%" alt="Forge: skill architect and builder — designs, scopes, builds, and validates new OCAS skills">

Skill design and construction for Hermes Agent. Runs a mandatory eight-phase pipeline: existence gate, research, classify, scope, architecture, plan, build, validate. Default output is the finished installable package.

**Skill name:** `ocas-forge`
**Version:** 3.7.1
**Type:** system
**Layer:** Architecture
**Author:** <agent-name>

---

## 📖 Overview

Builds and repairs agent skill packages. Default output is the finished package.

---

## 🔧 Commands

- `forge.build` — build a complete skill package
- `forge.critique` — review a package and identify defects
- `forge.repair` — fix broken files in an existing package
- `forge.classify` — classify a proposed skill by size class
- `forge.validate` — run structural validation
- `forge.scaffold` — generate a minimal package skeleton
- `forge.consolidate` — merge orphan or duplicate skill into its natural parent
- `forge.sync` — sync local skill changes to the canonical repository via PR
- `forge.verify-update` — check whether a skill is at the latest version
- `forge.audit` — audit skills for compliance, apply fixes, sync to GitHub
- `forge.status` — current build state if multi-step build in progress
- `forge.journal` — write journal for the current run
- `forge.update` — pull latest from GitHub source; preserves journals and data

---

## 📊 Outputs

Packages written to disk. Journals. Validation reports. PRs for sync operations.

---

## 📄 Files

| File | Purpose |
| --- | --- |
| `SKILL.md` | Skill definition with agentskills.io frontmatter |
| `CHANGELOG.md` | Release history |
| `references/` | Pipeline specs, authoring rules, ontology, schemas, workflow plans |
| `scripts/` | Build and validation scripts |
| `templates/` | Package scaffolding and file templates |
| `evals/` | Evaluation suites and metrics |
| `deferred/` | Out-of-scope material pending proper homes |

---

## Changelog

- **v3.7.1 (2026-07-13)** — Audit repair: restored missing manifest fields, fixed frontmatter validation errors, standardized templates/skill.json against schema.
- **v2.7.1 (2026-04-26)** — Version alignment: SKILL.md frontmatter, CHANGELOG.md, and GitHub release tag in sync. No functional change.
- **v2.7.0 (2026-04-18)** — Refactor: folded builder-domain helper skills into Forge's existing structure. SKILL.md shrunk to 343 lines. Added `forge.consolidate`, `forge.sync`, `forge.verify-update`. Moved runtime-harness guidance to `deferred/running-ocas-skills.md`. Moved OAuth/MCP setup content to `deferred/mcp-oauth-setup.md`.
- **v2.6.11 (2026-04-16)** — Authoring rules v2.7.2 -> v2.8.0. Ontology v2.0.1 -> v2.1.1. Active ecosystem updated.
- **v2.6.8 (2026-04-12)** — Fixed missing `{agent_root}/skills/` filesystem write path.
- **v2.6.0 (2026-04-08)** — Adopted agentskills.io open standard. Replaced skill.json hardcoding with {agent_root}/commons/ convention.

---

## 📚 Documentation

Read `SKILL.md` for operational details, schemas, and validation rules.

Read `references/` for detailed specifications and examples.

---

## 📄 License

MIT License — see `LICENSE` for details.
```
