This guide covers how to create artifacts, validate them, and contribute changes back to forge-core. Start with ARCHITECTURE.md for the structural overview — it defines artifacts, canon+sidecar, and the invariants.
How ideas become artifacts:
Internal (vault author) External (contributor)
┌─────────────────────┐ ┌──────────────────┐
│ Idea / draft │ │ Fork + branch │
│ in authoring env │ │ │
└────────┬────────────┘ └────────┬─────────┘
│ │
promote git push
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ forge-core module │
│ │
│ skills/YourSkill/ │
│ SKILL.md ← canon (AI instructions) │
│ SKILL.yaml ← sidecar (provider routing) │
└────────────────────────────┬────────────────────────────────┘
│
make install
│
┌───────────────┬───────┴───────┬───────────────┐
▼ ▼ ▼ ▼
.claude/skills/ .gemini/skills/ .codex/skills/ .opencode/skills/
Internal authors promote a copy from their authoring environment (e.g., Obsidian vault) into the module. External contributors fork, make changes, and open a PR. Both paths converge at the module — the single source of truth. make install deploys to all providers.
git clone https://github.com/N4M3Z/forge-core.git
cd forge-core
make install # deploy skills to all providers
make test # validate + run ADR self-testsPrerequisites:
forgeCLI on PATH (make installchecks this automatically)shellcheck(brew install shellcheck) for linting- At least one AI provider CLI (Claude Code, Gemini CLI, Codex, or OpenCode)
Each skill lives in its own directory under skills/ with two required files:
skills/YourSkill/
SKILL.md # Canon — provider-neutral AI instructions
SKILL.yaml # Sidecar — provider routing and metadata
Provider-neutral frontmatter + AI instructions in the body:
---
name: YourSkill
description: "What this skill does. USE WHEN trigger keywords."
version: "1.0.0"
---
Your AI instructions here.The description field drives skill discovery — providers match it against user requests. Use USE WHEN to list trigger keywords explicitly.
Provider-specific fields (e.g., argument-hint for Claude) go in the sidecar, not here.
Provider routing and deployment metadata. Consumed by build tooling, not by the AI directly:
sources:
- https://example.com/referenceCanon fields (name, description, version) live in SKILL.md only — never duplicate them here. See Separation of Concerns for why.
When SKILL.md needs to stay focused, split reference material into companion files loaded via @:
@ClaudeSkill.mdThe companion lives in the same directory. The @ reference injects its content at load time. Use companions for domain-specific patterns, examples, or templates that would clutter the main instructions. Keep them in the skill root — no subdirectories.
make install # deploy to providers
make test # validate + check conventionsHooks and markdown serve different roles:
| Hooks | Markdown (Build skills) | |
|---|---|---|
| When | Every matching event, unconditionally | When AI loads the skill |
| Purpose | Enforce mandatory rules | Document all conventions |
| Failure mode | Block the action | Advisory only |
Use hooks wherever a convention can be automated. Hook registration is platform-specific — each provider has its own mechanism for wiring hooks to events.
forge validate checks module structure and conventions:
make test # via Makefile
forge validate . # directlySkills should be structurally decomposed when complexity warrants it. Rather than enforcing a line count, the convention is:
- Main skill (SKILL.md): Entry point, high-level flow, gate checks
- Companion files (
@references): Domain-specific reference material, examples, templates - Sidecar (SKILL.yaml): Provider routing, never duplicates canon fields
If a skill's SKILL.md becomes difficult to follow as a single document, split it. See Skill Directory Structure and Conventions.
Conventional Commits: type: description. Lowercase, no trailing period, no scope.
Types: feat, fix, docs
- Fork the repository
- Create a branch for your change
- Make your changes following the conventions above
- Run
make testto validate - Open a PR against
main
CI runs validation on every PR. The main branch requires passing CI before merge.