Skip to content

Latest commit

 

History

History
151 lines (107 loc) · 6.48 KB

CONTRIBUTING.md

File metadata and controls

151 lines (107 loc) · 6.48 KB

Contributing to Forge

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.

Getting Started

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-tests

Prerequisites:

  • forge CLI on PATH (make install checks this automatically)
  • shellcheck (brew install shellcheck) for linting
  • At least one AI provider CLI (Claude Code, Gemini CLI, Codex, or OpenCode)

Creating a Skill

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

SKILL.md (canon)

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.

SKILL.yaml (sidecar)

Provider routing and deployment metadata. Consumed by build tooling, not by the AI directly:

sources:
    - https://example.com/reference

Canon fields (name, description, version) live in SKILL.md only — never duplicate them here. See Separation of Concerns for why.

Companion Files

When SKILL.md needs to stay focused, split reference material into companion files loaded via @:

@ClaudeSkill.md

The 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.

Deploy and Validate

make install    # deploy to providers
make test       # validate + check conventions

Hook Authoring

Hooks 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.

Validation

forge validate checks module structure and conventions:

make test            # via Makefile
forge validate .     # directly

Conventions

Structural Requirements

Skills 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.

Git

Conventional Commits: type: description. Lowercase, no trailing period, no scope.

Types: feat, fix, docs

Pull Requests

  1. Fork the repository
  2. Create a branch for your change
  3. Make your changes following the conventions above
  4. Run make test to validate
  5. Open a PR against main

CI runs validation on every PR. The main branch requires passing CI before merge.