██████╗      ██╗ █████╗ ███╗   ██╗ ██████╗  ██████╗      █████╗ ██████╗ ██╗
██╔══██╗     ██║██╔══██╗████╗  ██║██╔════╝ ██╔═══██╗    ██╔══██╗██╔══██╗██║
██║  ██║     ██║███████║██╔██╗ ██║██║  ███╗██║   ██║    ███████║██████╔╝██║
██║  ██║██   ██║██╔══██║██║╚██╗██║██║   ██║██║   ██║    ██╔══██║██╔═══╝ ██║
██████╔╝╚█████╔╝██║  ██║██║ ╚████║╚██████╔╝╚██████╔╝    ██║  ██║██║     ██║
╚═════╝  ╚════╝ ╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝     ╚═╝  ╚═╝╚═╝     ╚═╝
 █████╗ ██████╗  ██████╗██╗  ██╗██╗████████╗███████╗ ██████╗████████╗
██╔══██╗██╔══██╗██╔════╝██║  ██║██║╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝
███████║██████╔╝██║     ███████║██║   ██║   █████╗  ██║        ██║
██╔══██║██╔══██╗██║     ██╔══██║██║   ██║   ██╔══╝  ██║        ██║
██║  ██║██║  ██║╚██████╗██║  ██║██║   ██║   ███████╗╚██████╗   ██║
╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝   ╚═╝   ╚══════╝ ╚═════╝   ╚═╝

⚡ Django API Architect

Production-grade Django REST Framework API skills for AI coding agents, built around a service layer architecture.

imageValidate skills imageLicense: MIT imageAgent skills imageFormat imageTooling

Table of contents:

• Skills
• How they fit together
• Optional Django admin theme
• Install
• Usage
• Host agent profiles
• Validate
• Layout
• Credits
• Status and limits

Important

Principle: business logic lives in services and selectors; APIs, serializers and models stay thin interfaces over it.

Nine skills that let a coding agent build, review and extend Django REST API projects with confidence: app packs and project structure, thin DRF APIs with a stable error contract, a service and selector layer, pytest conventions, JWT and OTP authentication, Celery task wiring, and Docker images plus a local Compose stack. They follow the open Agent Skills format and work in Claude Code, Codex, Cursor, Copilot, OpenCode, or any SKILL.md-compatible agent. They are grounded in a production Django API starter (team-written) and the public Django Styleguide (credited as supporting theory).

Install supplied Claude Code, GitHub Copilot or Codex agent profiles into a project with python scripts/install_agents.py --host claude-code --target PATH. Other compatible hosts receive the skills only. The installer adds profiles to existing host agent folders and preserves unrelated files.

🧩 Skills

🗺️ How they fit together

flowchart TD
    R["⚡ django-api-architect<br/>routes by layer, enforces shared guardrails"]
    R --> A["🏗️ django-project-structure<br/>app packs, manifests, settings"]
    R --> C["🔌 django-apis-serializers<br/>thin APIs, serializers, error contract"]
    R --> S["⚙️ django-services-selectors<br/>business logic, validation, transactions"]
    R --> T["✅ django-testing<br/>pytest layout, mock boundaries"]
    R --> A2["🔑 django-auth<br/>JWT, OTP, admin second factor"]
    R --> K["📨 django-celery<br/>tasks, retries, webhooks"]
    R --> D1["🐳 django-docker-images<br/>Dockerfile, non-root, production server"]
    R --> D2["🧱 django-docker-compose<br/>local stack, health-gated startup, env files"]
    R --> OB["🏦 django-open-banking<br/>BlinkPay payments and account data, provider-agnostic"]
    R --> SUB["🔁 django-subscriptions<br/>plans, lifecycle, webhook-driven state, dunning"]

Route first with django-api-architect, then work in dependency order: structure, services and selectors, APIs, auth and tasks, tests throughout.

Optional Django admin theme

For projects that also need a modern Django admin interface, Unfold is an optional theme for dashboards and internal tools. It is separate from the API architecture taught here. Use the Django REST framework documentation and Django 6.1 documentation for framework behaviour. The service-layer approach is a project choice informed by the Django Styleguide, not a Django requirement.

📦 Install

Tip

Install the router skill plus every sibling skill it links to; routers reference siblings by relative path.

Claude Code plugin (installs the skills and both agent profiles together):

/plugin marketplace add KinwiseNZ-DevOps/django-api-architect
/plugin install django-api-architect@django-api-architect-marketplace

ChatGPT desktop plugin (local, skills and bundled hooks):

This repo has a portable plugin.json manifest and a marketplace at .agents/plugins/marketplace.json. Open this repo as a trusted project and restart ChatGPT desktop, then install Django API Architect from the Plugins Directory. Review and trust bundled hook scripts before they run.

Or copy or symlink the skills/ subfolders you want into your agent's skills directory:

Always on

In Claude Code, Django API Architect loads a short ruleset into every session as soon as the plugin is installed (thin APIs, logic in services and selectors, environment-driven settings, Docker conventions). It tells you its state at the start of each session and costs roughly 450 tokens.

• Say "stop django mode" to pause it for the current session, and "start django mode" to resume.
• Ask Claude to set the saved mode to on, off or auto. It writes that word into ~/.claude/.django-api-architect.mode. You can also edit that file yourself, and deleting it returns to the default (on).
• It needs Node on the machine, because the start-up hook runs a small Node script. Without Node the hook quietly does nothing.
• Other agents have no start-up hook here. Paste skills/django-api-architect/references/always-on-rules.md into that agent's instruction file instead.

Safety checks

The same hooks run a few checks while you work. Each one only asks, warns or adds a reminder; none changes your files on its own.

Switch any check with ~/.claude/.django-api-architect.features.json, for example {"packageGuard": false, "sessionLog": true}, or ask Claude to write it. The saved mode (on, off or auto) applies to every check. If several of these plugins are installed, each risky action is checked once, not once per plugin.

Privacy: packageGuard and licenseGuard send package names, and linkGuard sends the links it checks, to the public registry or site. Nothing else leaves your machine. Turn those checks off if that is a concern.

🚀 Usage

Tip

You never need to memorise skill names. Just describe the problem in plain words; the router picks the right skill automatically. But if you want short, reliable phrases that always work, use these:

The flow (this is all most people need):

1. "Add a billing feature"      → structure skill: new pack, manifest, routes
2. "Write the refund logic"     → services skill: service, validation, transaction
3. "Expose it as an endpoint"   → APIs skill: thin APIView, serializers, schema

Short phrases that trigger each skill:

Note

Skills also trigger on their own when your request matches. In Claude Code you can also invoke one explicitly with /<skill-name>, but the plain phrases above are shorter and work across every agent.

Host agent profiles

When a skill is invoked, its router uses the django-api-architect-workflow main profile for normal requests, planning, implementation, and review. It can use django-api-architect-debugger as the optional debugging helper. Each host has at most these two profiles. Prefixing names with the skill slug helps avoid clashes when profiles are installed alongside agents from other skills.

Host profiles are provided for GitHub Copilot and Claude Code. Codex role briefs are provided in resources/agents/codex/; after install_agents.py --host codex they sit in the target project's agents/codex/, and Codex reads them when the router skill directs it, and can use native subagent delegation when the runtime provides it. The Codex briefs are prompt templates, not automatically discovered profiles. Other SKILL.md-compatible hosts can follow the router skill directly or use the role briefs as prompt material. Copy the relevant host profiles into the project where you install the skills; installing a skill alone does not install host agent profiles.

✅ Validate

python scripts/skills_tool.py check

Checks: frontmatter, name/folder match, description length and trigger, body under 500 lines, every relative link resolves (including README.md and AGENTS.md), agent profile naming with no more than two profiles per host and exactly one -workflow main agent, at least 3 eval cases per skill, catalogue freshness, no project-specific terms from reference-content/strip-terms.txt, and no em or en dashes in file names or in any text outside reference-content/. After the starter skill is deleted it also rejects leftover placeholders and setup-only paths that are tracked by Git or not ignored. Stdlib only, no dependencies.

🗂️ Layout

Repository layout

skills/<name>/SKILL.md       one folder per skill (+ references/ where needed)
.github/agents/*.agent.md    optional GitHub Copilot agents
.claude/agents/*.md          optional Claude Code project agents
resources/agents/            host profile sources (Claude Code, Copilot, Codex)
.claude-plugin/              plugin.json and marketplace.json (Claude Code plugin)
evals/cases.jsonl            3+ behavioural cases per skill
scripts/skills_tool.py       validate, regenerate catalogue (stdlib only)
.github/workflows/           CI runs `skills_tool.py check` (free on public repos)
AGENTS.md                    agent-facing rules for this repo

🙏 Credits

Details in the skills are checked against the official documentation, linked from the skill that uses them:

• Django REST framework: permissions and throttling behaviour.
• Django documentation: transactions and on_commit.
• Django Styleguide: the service and selector layer theory.

📌 Status and limits

Note

• The skills teach a primary architecture from an in-house Django API starter; projects with different structures win where they differ, and the router states that explicitly.
• Throttle rates, quotas and provider credentials are per project; the skills describe patterns, not values.
• Licensed under MIT (see LICENSE).

⚡ Built on the Agent Skills open format · grounded in an in-house Django API starter and the Django Styleguide