A build system for AI instructions. Treats prompts the way software engineering treats source code: authored in version-controlled markdown, validated by schemas, assembled per target, deployed with provenance records.
Three artifact types map to how Claude Code loads instructions:
- Rules — small instruction files, always in context. One file, one behavior. When something goes wrong, the filename tells you which rule caused it.
- Skills — lazy-loaded capabilities. The AI reads the description at session start but loads full instructions only when invoked.
- Agents — markdown files that define a persona and role for agent delegation.
This is not a plugin system. Plugins are deployed artifacts for end users (one-click install via Cowork). forge is what happens before that: authoring, validating, assembling, and tracking instructions across teams, models, and providers.
See ARCHITECTURE.md for the structural overview. See CONTRIBUTING.md for how to contribute.
Deploys to Claude Code, Gemini CLI, Codex, and OpenCode:
make install # all providers
SCOPE=user make install # ~/.claude/skills/ (global)
SCOPE=workspace make install # ./.claude/skills/ (project-local)Have your AI resolve the install instructions:
curl -s https://raw.githubusercontent.com/N4M3Z/forge-core/main/INSTALL.md | claudeOr manually:
git clone https://github.com/N4M3Z/forge-core.git
cd forge-core
make install # requires forge-cli (https://github.com/N4M3Z/forge-cli)make install deploys skills to all providers and activates git pre-commit hooks. See INSTALL.md for the full agent-executable setup.
Skills teach AI coding tools new capabilities. Invoke them with /SkillName in Claude Code, or reference them in prompts for other providers. Rules enforce behavioral conventions automatically.
| Skill | What it does |
|---|---|
| BuildSkill | Create and validate skill definitions |
| BuildAgent | Scaffold, validate, and audit agent definitions |
| BuildModule | Design and validate forge modules |
| BuildHook | Hook registration, event handling, platform wiring |
| BuildPlugin | Create, validate, and publish Claude Code plugins |
| ArchitectureDecision | Find, create, validate, and capture ADRs with schema validation |
| VersionControl | Git conventions, repo governance, CODEOWNERS, worktrees |
| BashConventions | Bash pitfalls — BSD vs GNU, set -euo pipefail traps, subprocess env |
| MarkdownConventions | Markdown authoring and linting conventions |
| MarkdownSchema | Create, derive, and validate .mdschema files |
| PublishArtifact | Ship artifacts (rules, skills, agents) into downstream repos |
| RefinePrompt | Refine prompts (align, debrand, minimize, rescope, extract, adapt) |
| PromptAnalysis | Validate and minimize prompts |
| SettingsMaintenance | Audit and clean AI tool settings |
| SystemCheck | Ecosystem staleness and version drift checks |
| RTK | Token-optimized CLI proxy |
| HtmlPlayground | Generate single-file HTML demos comparing techniques |
| Brainstorming | Collaborative ideation before implementation |
| DesignSpec | Formal design spec from brainstorming output |
| WritePlan | Bite-sized implementation plans with plan mode |
| ExecutePlan | Inline sequential plan execution |
| VerifyCompletion | Evidence-based verification gate |
Architecture Decision Records document the why behind structural choices. Each prefix section numbers independently:
| Prefix | Scope | Example |
|---|---|---|
CORE |
Markdown and scaffolding | CORE-0001 Markdown as System Language |
ARCH |
Ecosystem architecture | ARCH-0001 Skills Agents and Rules |
PROV |
Manifest and provenance | PROV-0002 Manifest for Deployment Tracking |
MVPR |
Prompt optimization | MVPR-0001 Minimum Viable Prompt |
ADRs use structured-madr frontmatter with forge extensions. Validated by forge validate ..
See CONTRIBUTING.md for the development workflow, skill authoring conventions, and PR process.
| Dependency | Required | Purpose |
|---|---|---|
| forge-cli | Yes | Module validation and deployment |
| shellcheck | Recommended | Shell script linting |
| ruff | Recommended | Python linting |
Workflow skills (Brainstorming, DesignSpec, WritePlan, ExecutePlan, VerifyCompletion) and behavioral patterns (rationalization resistance, pressure testing, Red Flags tables) adapted from superpowers by Jesse Vincent.