OpenFGA Best Practices Skill

A comprehensive skill for AI agents to author, review, and refactor OpenFGA authorization models following best practices.

Installation

npx skills add openfga/agent-skills

What’s Included

This skill provides guidelines and patterns for:

• Authorization Model Design - Types, relations, and permission structures
• Relationship Patterns - Direct, concentric, indirect, and conditional relationships
• Testing & Validation - .fga.yaml test files and CLI usage
• Custom Roles - User-defined roles and role assignments
• SDK Integration - Code examples for JavaScript, Go, Python, Java, and .NET

Rule Categories

When This Skill Activates

The skill triggers when working with:

• .fga model files
• .fga.yaml test files
• OpenFGA relationship definitions
• Permission structures and authorization logic
• OpenFGA SDK code in any supported language

SDK Support

Includes complete examples for:

• JavaScript/TypeScript - @openfga/sdk
• Go - github.com/openfga/go-sdk
• Python - openfga_sdk (async and sync)
• Java - dev.openfga:openfga-sdk
• .NET - OpenFga.Sdk

File Structure

openfga/
├── SKILL.md              # Skill metadata, rule index, and workflow
├── AGENTS.md             # Generated comprehensive guide (all rules expanded)
└── references/
    ├── core-*.md         # Core concept references
    ├── relation-*.md     # Relationship pattern references
    ├── design-*.md       # Design pattern references
    ├── roles-*.md        # Custom role references
    ├── optimize-*.md     # Optimization references
    ├── test-*.md         # Testing references
    ├── workflow-*.md     # Workflow references
    └── sdk-*.md          # SDK-specific references

Rebuilding AGENTS.md

The AGENTS.md file is generated from the individual reference files. To regenerate it after making changes:

node scripts/build-agents-md.js

The script reads:

• Section order and rule order from the Rule Index tables in skills/openfga/SKILL.md
• Individual rule content from skills/openfga/references/*.md

When adding new rules:

1. Create the rule file in references/ with the appropriate prefix (e.g., core-, relation-, test-)
2. Add the rule to the corresponding table in the Rule Index section of SKILL.md
3. Run the build script to regenerate AGENTS.md

Example Usage

Once installed, AI agents will automatically apply these best practices when: