Skip to content

Architecture

SkillForge separates portable skill specifications from assistant-specific directory layouts, providing a clean boundary between skill authoring, security auditing, and editor installation.

High-Level Architecture

┌────────────────────────────────────────────────────────┐
│           Portable SKILL.md Directory Package          │
│    (YAML Frontmatter + Markdown + scripts/ + refs/)    │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
               ┌─────────────────────────┐
               │  SkillPackage & Model   │
               │   (Schema Validation)   │
               └────────────┬────────────┘
                            │
            ┌───────────────┴───────────────┐
            ▼                               ▼
┌───────────────────────┐       ┌───────────────────────┐
│     SkillAuditor      │       │       Registry        │
│  - Zero-width unicode │       │  - BuiltinRegistry    │
│  - Prompt injections  │       │  - LocalRegistry      │
│  - Script exfil check │       │  - GitRemoteRegistry  │
└───────────────────────┘       └───────────┬───────────┘
                                            │
                      ┌─────────────────────┴─────────────────────┐
                      ▼                                           ▼
          ┌───────────────────────┐                   ┌───────────────────────┐
          │     CLI Interface     │                   │      MCP Server       │
          │ (add, audit, list, rm)│                   │(search, get, validate,│
          └───────────┬───────────┘                   │     audit_skill)      │
                      │                               └───────────────────────┘
                      ▼
          ┌───────────────────────────────────────────────────┐
          │                Assistant Adapters                 │
          │ - ClaudeCodeAdapter (.claude/skills/)             │
          │ - CursorAdapter (.cursor/skills/)                 │
          │ - AntigravityAdapter (.gemini/config/skills/)     │
          │ - WindsurfAdapter (.windsurf/skills/)             │
          │ - ClineAdapter (.cline/skills/)                   │
          │ - AgentsMarkdownAdapter (AGENTS.md)               │
          │ - CopilotAdapter (.github/copilot-instructions.md)│
          └───────────────────────────────────────────────────┘

Component Boundaries

  1. Document Model (skill.py):
  2. Strictly enforces the AAIF agentskills.io specification.
  3. Skill: Represents the parsed metadata (name, description, license, compatibility, metadata, allowed-tools) and body text.
  4. SkillPackage: Represents the multi-file directory bundle containing execution helper scripts (scripts/), in-depth reference documentation (references/), and static assets (assets/).

  5. Security Engine (security.py):

  6. Evaluates packages and raw content before execution or installation.
  7. Decoupled from network and filesystem access so it can be called synchronously in CLI commands or asynchronously via MCP tools.

  8. Registries (registry.py):

  9. LocalRegistry: Manages on-disk directories under .skillforge/.
  10. BuiltinRegistry: Ships 16 battle-tested engineering workflows packaged with the library.
  11. GitRemoteRegistry: Clones or updates remote Git/GitHub repositories into ~/.skillforge/cache/ using shallow clones.
  12. CompositeRegistry: Merges multiple registry backends with explicit priority order.

  13. Adapters (adapters.py):

  14. Isolated installation targets. Each adapter knows how to detect its target environment, install single files or complete directory bundles, list active skills, and cleanly remove unneeded skills.