{
  "markdown": "# MASA Skill — AI Agent Instruction Set\n\n> 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.\n\n📄 **Read the full study:** [www.masa-framework.org](https://www.masa-framework.org/)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## What Is This?\n\nThis 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.\n\nWhen an agent has this skill loaded, it will:\n\n- **Scaffold** new projects with the correct 5-layer structure\n- **Enforce** unidirectional dependency rules between layers\n- **Name** files and functions with semantic intent (not technical jargon)\n- **Isolate** infrastructure from business logic automatically\n- **Detect** architectural violations before they ship\n\n### Supported Languages\n\n- Python\n- JavaScript / TypeScript\n- Go\n\n## Quick Start\n\n### GitHub Copilot (Custom Instructions)\n\n1. Copy `SKILL.md` to your project root (or `.github/copilot-instructions.md`):\n\n```bash\n# Option A: As a project-level skill file\ncp SKILL.md your-project/.github/copilot-instructions.md\n\n# Option B: As a standalone file referenced in settings\ncp SKILL.md your-project/SKILL.md\n```\n\n2. Copilot will automatically pick up the instructions and apply MASA patterns when generating code in that project.\n\n> **Tip:** For VS Code, you can also add it to your workspace settings under `github.copilot.chat.codeGeneration.instructions`.\n\n### Claude Code (Plugin)\n\nInstall as a Claude Code plugin for the best experience — includes slash commands and auto-invoked skills:\n\n```bash\n# Install from the official Claude Code marketplace (in review)\n/plugin install masa\n\n# Or add from the GitHub marketplace manually\n/plugin marketplace add nicolasfmelo/masa-skill\n/plugin install masa@masa-skill\n```\n\nOnce installed, you get these slash commands:\n\n| Command | What It Does |\n|---------|-------------|\n| `/masa:new-feature [description]` | Walk through the 5-step protocol for a new feature |\n| `/masa:validate` | Audit current code for MASA compliance |\n| `/masa:audit [layer]` | Full audit of a layer's imports, naming, and compliance |\n| `/masa:refactor` | Propose a MASA-compliant refactoring |\n| `/masa:explain [rule]` | Explain a ruleset with language-specific examples |\n| `/masa:scaffold [language]` | Generate the full MASA directory skeleton |\n\nPlus, the **masa-framework** skill is auto-invoked by Claude when it detects architecture-related tasks.\n\n#### Example Use Cases\n\n```bash\n# Scaffold a new Python project with the full MASA directory structure\n/masa:scaffold python\n\n# Implement a new feature following the 5-layer protocol\n/masa:new-feature create JWT authentication system\n\n# Audit the services layer for dependency violations\n/masa:audit services\n\n# Check if the current file follows MASA rules\n/masa:validate\n\n# Refactor legacy code toward MASA compliance\n/masa:refactor\n\n# Learn about a specific rule with code examples\n/masa:explain data-dressing\n```\n\n### Claude Code (Standalone)\n\nIf you prefer not to use the plugin, add the skill as project instructions:\n\n```bash\n# Copy to your project\ncp SKILL.md your-project/SKILL.md\n\n# Reference it in your CLAUDE.md or project instructions\necho \"Follow the architecture rules in SKILL.md\" >> your-project/CLAUDE.md\n```\n\n### OpenAI Codex\n\nLoad the skill as a system-level or project-level instruction:\n\n```bash\n# Copy the skill file into your project\ncp SKILL.md your-project/SKILL.md\n\n# Reference in your AGENTS.md\necho \"Follow the architecture defined in SKILL.md for all code generation.\" >> your-project/AGENTS.md\n```\n\nCodex will use the SKILL.md as architectural context when generating or modifying code within the project.\n\n### Any Other AI Agent\n\nThe skill file is plain Markdown with structured rules. You can integrate it with any agent that accepts system prompts or instruction files:\n\n```\nInclude the contents of SKILL.md in your agent's system prompt or project-level context.\n```\n\n## Repository Structure\n\n```\nmasa-skill/\n├── .claude-plugin/\n│   └── plugin.json                   # Claude Code plugin manifest\n├── commands/                         # User-invocable slash commands (/masa:*)\n│   ├── new-feature.md\n│   ├── validate.md\n│   ├── audit.md\n│   ├── refactor.md\n│   ├── explain.md\n│   └── scaffold.md\n├── skills/\n│   └── masa-framework/\n│       └── SKILL.md                  # Auto-invoked skill (model-triggered)\n├── SKILL.md                          # Standalone skill file (for non-plugin agents)\n├── references/\n│   ├── pillars.md                    # The Four Pillars — deep dive\n│   ├── rulesets.md                   # Five Agentic Rulesets with examples\n│   ├── task-execution-protocol.md    # Step-by-step feature implementation workflow\n│   ├── validation.md                 # Violation detection catalog\n│   └── languages/\n│       ├── python.md                 # Python-specific patterns\n│       ├── javascript.md             # JavaScript/TypeScript patterns\n│       └── go.md                     # Go patterns\n├── LICENSE                           # MIT\n└── README.md                         # This file\n```\n\n### What Each File Does\n\n| File | Purpose | When to Use |\n|------|---------|-------------|\n| **`.claude-plugin/plugin.json`** | Plugin manifest for Claude Code | Plugin installation |\n| **`commands/*.md`** | Slash commands (`/masa:new-feature`, etc.) | User-invoked commands |\n| **`skills/masa-framework/SKILL.md`** | Auto-invoked skill — Claude uses it automatically | Architecture tasks |\n| **`SKILL.md`** | Standalone skill file for non-plugin agents | Copilot, Codex, etc. |\n| `references/pillars.md` | Detailed explanation of the four architectural pillars | Deep understanding |\n| `references/rulesets.md` | Five rulesets with code examples in Python, TS, Go | Implementing features |\n| `references/validation.md` | Violation catalog with detection patterns | Code review / auditing |\n| `references/task-execution-protocol.md` | Step-by-step workflow for implementing features | New feature development |\n| `references/languages/*.md` | Language-specific conventions and project layouts | Starting a new project |\n\n> **Plugin users:** Just install the plugin — everything works automatically.\n> **Non-plugin users:** Load `SKILL.md` into your agent. The references are supplementary.\n\n## Available Commands\n\nOnce the plugin is installed (or skill is loaded), these commands are available:\n\n| Command | What It Does |\n|---------|-------------|\n| `/masa:new-feature [description]` | Walk through the 5-step protocol for a new feature |\n| `/masa:validate` | Audit current code for MASA compliance |\n| `/masa:audit [layer]` | Full audit of a layer's imports, naming, and compliance |\n| `/masa:refactor` | Propose a MASA-compliant refactoring |\n| `/masa:explain [rule]` | Explain a ruleset with language-specific examples |\n| `/masa:scaffold [language]` | Generate the full MASA directory skeleton |\n\n## The MASA Architecture at a Glance\n\n```\n┌─────────────────────────────────────────────┐\n│  Delivery        HTTP handlers, CLI, events │\n├─────────────────────────────────────────────┤\n│  Services        Orchestration, workflows   │\n├─────────────────────────────────────────────┤\n│  Engines         Pure business logic        │\n├─────────────────────────────────────────────┤\n│  Integrations    DB repos, API clients      │\n├─────────────────────────────────────────────┤\n│  Domain Models   Entities, value objects     │\n└─────────────────────────────────────────────┘\n```\n\n**Dependency rule:** each layer may only import from layers below it.\n\n## Empirical Evidence\n\nMASA has been empirically evaluated against DDD/Clean Architecture baselines across three complexity tiers (low, medium, high) with multiple AI model tiers. Key findings:\n\n- **+30–35% improvement** in composite cognizability score\n- **0 architectural violations** (vs. 1–22 in baselines)\n- **100% task pass rate** maintained in both architectures\n\nFull experiment data, reproduction instructions, and analysis are available in the companion research repository: **[nicolasfmelo/masa-framework](https://github.com/nicolasfmelo/masa-framework)**\n\n## Contributing\n\nContributions, critiques, and empirical evaluations are welcome. Open a discussion, submit a pull request, or reach out directly.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 8499,
  "sha": "5a8542854ed78e4bc5e56df25ba2abdb0301417180716e1e92bb15596f40a0db",
  "repo_slug": "nicolasfmelo/masa-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nicolasfmelo_masa_skill_masa_db5eb770/readme"
}