openfga/agent-skills

Overview

This skill provides concise best practices and guidelines for authoring, reviewing, and refactoring OpenFGA authorization models. It focuses on model correctness, relationship patterns, testing, role design, optimization, and SDK integration across JavaScript, TypeScript, Go, Python, Java, and .NET. Use it to make models predictable, testable, and performant.

How this skill works

The skill inspects OpenFGA schema and tuple patterns, highlighting core concept violations such as missing types, improper relations, and schema-version mismatches. It checks model design choices (permission naming, hierarchy, modules), suggests relationship patterns (direct, usersets, inheritance), and recommends tests and SDK usage patterns. It also recommends optimizations to reduce tuple counts and improve query performance.

When to use it

• Creating or updating .fga schema files
• Writing or refactoring relationship tuples and relations
• Designing permission and hierarchy models for resources
• Authoring .fga.yaml test suites and check/list assertions
• Integrating OpenFGA with JS/TS, Go, Python, Java, or .NET SDKs
• Reviewing or validating models before deployment

Best practices

• Always define types for every entity class and use schema 1.1
• Keep schema (model) separate from data (tuples); avoid mixing concerns
• Model permissions as explicit can_* relations and use clear, consistent naming
• Favor usersets and indirect relationships to reduce tuple volume and support inheritance
• Write .fga.yaml tests for checks, list_objects, and list_users; validate conditional rules with context
• Validate models with tooling/CLI before merging or deploying changes

Example use cases

• Authoring a new model for multi-tenant document access with organization and team hierarchies
• Refactoring a bloated tuple set into usersets and hierarchical relations to improve performance
• Writing .fga.yaml test cases that assert expected permission outcomes for edge cases and conditional logic
• Implementing custom roles that combine static assignments and resource-scoped roles
• Integrating OpenFGA checks in a TypeScript backend to enforce authorization at API boundaries