masa-skill

MASA Skill — AI Agent Instruction Set

Teach your AI coding agent the Modular Agentic Semantic Architecture (MASA) — a framework that maximizes how well agents can understand, navigate, and safely modify your codebase.

📄 Read the full study: www.masa-framework.org

What Is This?

This repository contains the MASA skill file — a structured instruction set that you load into AI coding agents so they follow MASA architectural patterns when writing, reviewing, or refactoring code.

When an agent has this skill loaded, it will:

• Scaffold new projects with the correct 5-layer structure
• Enforce unidirectional dependency rules between layers
• Name files and functions with semantic intent (not technical jargon)
• Isolate infrastructure from business logic automatically
• Detect architectural violations before they ship

Supported Languages

• Python
• JavaScript / TypeScript
• Go

Quick Start

GitHub Copilot (Custom Instructions)

1. Copy SKILL.md to your project root (or .github/copilot-instructions.md):

# Option A: As a project-level skill file
cp SKILL.md your-project/.github/copilot-instructions.md

# Option B: As a standalone file referenced in settings
cp SKILL.md your-project/SKILL.md

2. Copilot will automatically pick up the instructions and apply MASA patterns when generating code in that project.

Tip: For VS Code, you can also add it to your workspace settings under github.copilot.chat.codeGeneration.instructions.

Claude Code (Plugin)

Install as a Claude Code plugin for the best experience — includes slash commands and auto-invoked skills:

# Install from the official Claude Code marketplace (in review)
/plugin install masa

# Or add from the GitHub marketplace manually
/plugin marketplace add nicolasfmelo/masa-skill
/plugin install masa@masa-skill

Once installed, you get these slash commands:

Command	What It Does
/masa:new-feature [description]	Walk through the 5-step protocol for a new feature
/masa:validate	Audit current code for MASA compliance
/masa:audit [layer]	Full audit of a layer's imports, naming, and compliance
/masa:refactor	Propose a MASA-compliant refactoring
/masa:explain [rule]	Explain a ruleset with language-specific examples
/masa:scaffold [language]	Generate the full MASA directory skeleton

Plus, the masa-framework skill is auto-invoked by Claude when it detects architecture-related tasks.

Example Use Cases

# Scaffold a new Python project with the full MASA directory structure
/masa:scaffold python

# Implement a new feature following the 5-layer protocol
/masa:new-feature create JWT authentication system

# Audit the services layer for dependency violations
/masa:audit services

# Check if the current file follows MASA rules
/masa:validate

# Refactor legacy code toward MASA compliance
/masa:refactor

# Learn about a specific rule with code examples
/masa:explain data-dressing

Claude Code (Standalone)

If you prefer not to use the plugin, add the skill as project instructions:

# Copy to your project
cp SKILL.md your-project/SKILL.md

# Reference it in your CLAUDE.md or project instructions
echo "Follow the architecture rules in SKILL.md" >> your-project/CLAUDE.md

OpenAI Codex

Load the skill as a system-level or project-level instruction:

# Copy the skill file into your project
cp SKILL.md your-project/SKILL.md

# Reference in your AGENTS.md
echo "Follow the architecture defined in SKILL.md for all code generation." >> your-project/AGENTS.md

Codex will use the SKILL.md as architectural context when generating or modifying code within the project.

Any Other AI Agent

The skill file is plain Markdown with structured rules. You can integrate it with any agent that accepts system prompts or instruction files:

Include the contents of SKILL.md in your agent's system prompt or project-level context.

Repository Structure