Methodology Frameworks
Relevant source files
The following files were used as context for generating this wiki page:
The Methodology Framework in SkillKit provides a composable, community-driven system for AI coding agents. It supports a wide variety of development approaches—such as Test-Driven Development (TDD), Behavior-Driven Development (BDD), and Design-First—through installable "packs" of related skills. The framework is methodology-agnostic and designed to work across 17 different AI agent formats by translating specialized instructions into agent-specific formats like .cursorrules or CLAUDE.md.
Sources: packages/core/src/methodology/index.ts:1-12, packages/core/src/skill-translator.ts:257-261
Framework Architecture
The framework is structured into three primary layers: the Management Layer (Manager and Loader), the Data Layer (Packs and Skills), and the Translation Layer.
Component Relationship
The following diagram illustrates the relationship between the Methodology Packs, the constituent Skills, and the resulting state within a project.
Key Data Structures
The system relies on specific interfaces to define the behavior and metadata of methodologies.
| Interface | Description | Key Fields |
|---|---|---|
MethodologyPack | Defines a collection of related skills. | name, version, skills, compatibility, dependencies |
MethodologySkill | Represents an individual unit of methodology. | id, name, pack, content, metadata |
MethodologySkillMetadata | Frontmatter metadata from a SKILL.md file. | triggers, relatedSkills, difficulty, estimatedTime |
MethodologyState | Persisted state of installed methodologies. | installedPacks, installedSkills, lastSync |
Sources: packages/core/src/methodology/types.ts:17-111
Methodology Packs
Methodology Packs are organized collections of skills. Built-in packs include common engineering workflows like tdd, agile, devops, and security-first. These packs are managed via a lifecycle that includes discovery, installation, and synchronization.
Installation and Sync Flow
When a user installs a methodology, the framework manages the local state and prepares the skills for the specific AI agents active in the project.
Skill Translation and Agent Compatibility
A core feature of the framework is "Universal Translation." This ensures that a methodology written as a SKILL.md file can be used by 17 different agents, including Claude Code, Cursor, Windsurf, and GitHub Copilot.
Supported Agent Formats
The skill-translator converts the canonical skill representation into specific files required by various agents.
| Agent | Config File | Format Type |
|---|---|---|
| Claude Code | CLAUDE.md | XML-style |
| Cursor | .cursor/rules/skills.mdc | MDC (Markdown + YAML) |
| Windsurf | .windsurf/rules/skills.md | Markdown |
| GitHub Copilot | .github/copilot-instructions.md | Markdown |
| Codex | AGENTS.md | Markdown Table |
| Gemini CLI | AGENTS.md | JSON |
Sources: packages/core/src/skill-translator.ts:31-41, packages/core/src/tests/skill-translator.test.ts:60-95
Translation Logic
The translation process preserves agent-specific fields (like hooks for Claude Code or globs for Cursor) while transforming the body of the skill into the target agent's preferred instructional style.
Skill Authoring Standards
Skills within the methodology framework follow a specific anatomy defined in SKILL.md files. This includes YAML frontmatter for triggers and markdown for core principles and process steps.
Structure of a Methodology Skill
A standard skill file must include:
- Frontmatter: Meta-information like
triggers(keywords to activate the skill) anddifficulty. - Core Principle: A single, bolded rule that defines the methodology.
- Process/Stages: Actionable, step-by-step guidance for the agent.
- Checklists: Verification criteria to ensure the methodology was applied correctly.
---
name: Design First
triggers: [design first, architecture]
difficulty: intermediate
---
# Design First Methodology
**Think first, code second. A good design makes implementation straightforward.**
...
Sources: packages/core/src/methodology/packs/planning/design-first/SKILL.md:1-20, packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:23-56
Integration with the Plan System
The Methodology Framework integrates directly with the project's planning system. This allows users to create execution plans that are constrained or guided by specific methodologies, such as a "TDD Feature Plan" that enforces the red-green-refactor cycle.
Integration Flow
Summary
Methodology Frameworks in SkillKit enable consistent engineering standards across diverse AI coding agents. By abstracting methodologies into reusable, translatable packs, the framework ensures that specialized workflows—from high-level architecture design to low-level root cause analysis—remain portable and actionable regardless of the specific AI tool being utilized.