WoJiSama/skill-based-architecture

What it solves

Coding agents often struggle with fragmented project rules, duplicated instructions across multiple files (like CLAUDE.md or .cursorrules), and a lack of clear "definition of done." Skill-Based Architecture (SBA) centralizes these scattered instructions into a single, routable, and verifiable project "Skill," ensuring agents follow the project's actual business logic and architectural rules without guessing implementation scope.

How it works

SBA provides a project-level operating contract that the agent uses to navigate the repository. Instead of loading one massive instruction file, the agent:

1. Inventories the repository to identify existing rules.
2. Selects a specific workflow based on the user request.
3. Loads only the evidence and knowledge required for the current decision.
4. Binds business meaning to the current code owner.
5. Verifies the result against a requested terminal state rather than just treating a command or commit as "done."
6. Records reusable learning from failures to prevent them from recurring.

Who it’s for

Developers and teams managing repositories where project instructions have become too large to navigate, are contradictory across different agent entry files, or where recurring tasks require strict procedures and reliable completion checks.

Highlights

• Centralized Knowledge: Eliminates duplication across AGENTS.md, CLAUDE.md, and Cursor rules.
• Harness Agnostic: Compatible with Claude Code, Cursor, Windsurf, Gemini CLI, and other file-aware agents.
• Evidence-Based Execution: Uses a result-oriented lifecycle that returns to localization or decomposition if evidence invalidates the current premise.
• Automated Migration: Includes a scaffold tool that previews and applies the migration of existing rules into the SBA structure.
• Strict Completion Discipline: Defines "done" based on bound deliverables and terminal states rather than simple activity (e.g., a push or a commit).