directus

name

directus

description

Use when building, reviewing, debugging, or changing self-hosted Directus backends in SaaS repositories, especially behind an API proxy, gateway, or reverse proxy. The skill makes the agent inspect the repository architecture and versions first, research current official Directus and detected-stack docs, then plan, implement, and verify schema, environment, extension, auth, permissions, deployment, API, proxy, migration, security, observability, or AI/MCP changes without imposing a fixed reference stack.

Directus

Purpose

Use this skill to work on a SaaS backend that already has Directus architecture in the repository. Treat the repository as the source of local truth and current official documentation as the source of external truth.

The expected target is self-hosted Directus used as a backend or data platform behind an API proxy, gateway, or reverse proxy. The exact database, proxy, auth provider, deployment model, CI/CD, framework, and observability stack must be discovered from the repository unless the user explicitly specifies them.

When To Use

Use this skill for:

• Directus backend architecture reviews.
• Directus schema, migrations, snapshots, or promotion work.
• Directus permissions, roles, policies, auth, SSO, or service-account changes.
• Directus API proxy, gateway, reverse proxy, route, CORS, cookie, websocket, or upload changes.
• Directus extensions, hooks, endpoints, flows, services, or SDK work.
• Directus self-hosting, deployment, scaling, storage, cache, synchronization, metrics, or observability work.
• Directus AI/MCP configuration or security review.

When Not To Use

Do not use this skill for:

• Generic headless CMS explanations.
• Greenfield SaaS architecture where Directus is not required.
• Unrelated frontend, spreadsheet, document, or design work.
• Copying generic Directus examples into a repository without inspecting the local architecture.

Non-Negotiable Rules

1. Inspect the repository before proposing architecture or code changes.
2. Determine the Directus version and deployment mode before relying on Directus behavior.
3. Research current official documentation before non-trivial Directus, proxy, auth, migration, deployment, security, or AI/MCP recommendations.
4. Prefer official sources first: Directus docs, Directus GitHub and release notes, and official docs for detected stack components.
5. Do not introduce a new stack component unless the repository already uses it or the user explicitly asks for it.
6. Do not print secrets, tokens, cookies, database passwords, private keys, or raw .env values.
7. Do not run destructive schema/database migrations, data deletion, production deploys, or secret rotations without explicit user approval.
8. If web access is unavailable, say which documentation checks could not be completed and mark related conclusions as unverified.
9. Keep changes small, reversible, and testable unless the task explicitly requires a larger refactor.

Workflow

1. Classify the user task: review, implementation, schema, proxy, auth, deployment, extension, security, performance, observability, AI/MCP, or incident/debugging.
2. Inspect the repository for package files, Directus versions, Docker images, deployment files, proxy configs, environment examples, migrations, extensions, auth integrations, storage, observability, and tests.
3. Build a concise architecture inventory with confirmed facts, likely signals, unknowns, and confidence levels.
4. Research current official docs for Directus and detected stack components. Record source URLs and the claims they support.
5. Plan the smallest safe change against the existing architecture, including target files, verification, rollback, and open risks.
6. Implement using repository conventions. Preserve existing package manager, module style, deployment boundaries, secret-management path, and migration mechanism.
7. Verify with the repository's tests, linting, type checks, build checks, compose validation, extension checks, deployment dry-runs, or targeted smoke tests when available.
8. Adapt when evidence contradicts the initial plan. State remaining blockers instead of hiding uncertainty.

Optional Helper Scripts

The scripts/ directory contains dependency-free Node.js helpers. Use them only as read-only aids:

• scripts/discover-repo.mjs for a safe repository inventory.
• scripts/detect-directus-stack.mjs --format md for Directus stack signals.
• scripts/audit-directus-env.mjs for non-secret Directus environment review flags.
• scripts/build-research-queries.mjs to generate official-doc research queries from repo findings.

Helper output is not authoritative. Always verify findings against repository files and current official docs.

References

Load references only as needed:

• references/repo-first-workflow.md for full discovery and planning procedure.
• references/official-research-policy.md before documentation-dependent recommendations.
• references/directus-source-map.md to choose current official Directus docs to check.
• references/directus-implementation-guidance.md for coding, configuration, deployment, extensions, and observability concerns.
• references/api-proxy-integration.md for proxy, gateway, route, auth propagation, websocket, upload, and boundary review.
• references/security-and-access-control.md for RBAC, policies, tokens, secrets, tenant isolation, and AI/MCP safety.
• references/schema-and-migrations.md for schema snapshots, migrations, data-model changes, and rollout.
• references/feedback-loop.md when debugging or when repo findings contradict the initial plan.
• references/stack-detection-signals.md when repository structure is unfamiliar.

Output Expectations

For analysis or review tasks, provide:

• confirmed findings with source evidence
• risks ranked by practical impact
• recommended next changes
• documentation sources used
• explicit unknowns

For implementation tasks, provide:

• files changed
• why the approach matches the repo architecture
• verification performed and results
• docs checked
• unresolved risks

Keep responses direct. Avoid generic Directus tutorials unless the user asks for one.

Completion Criteria

The task is complete when repository evidence, official documentation checks, implementation or recommendations, verification results, and remaining risks are all explicit.