Skip to content

CLAUDE.md

Latest commit

 

History

History
86 lines (69 loc) · 4.39 KB

CLAUDE.md

File metadata and controls

86 lines (69 loc) · 4.39 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

A collection of skills for AI coding agents working with Constructive tooling. Skills are packaged instructions and scripts that extend agent capabilities for GraphQL development workflows, following the Agent Skills format.

Available Skills

Skill Description
constructive-features Feature catalog — one-page router mapping every app capability (auth, authz, multi-tenancy, storage, search, AI, GraphQL, ops) to the authoritative skill
constructive-platform Platform core — security model (Safegres), services/schemas, deployment, server config, cloud functions, env config, CNC CLI
constructive-safegres Safegres authorization protocol — all 14 Authz* policy types, config shapes, semantics, permissive/restrictive composition
constructive-setup Monorepo setup — install dependencies, start PostgreSQL via pgpm Docker, bootstrap users, build, run tests, local email services
pgpm PostgreSQL Package Manager — migrations, CLI, Docker, CI/CD workflows
constructive-pnpm PNPM workspace management — monorepo config, dist-folder publishing with makage/lerna, dependency management
constructive-sdk-graphql SDK GraphQL — codegen (hooks, ORM, CLI), runtime queries, search (all algorithms), pagination
constructive-sdk-entities Entity types — custom entities (channels, teams, data rooms), memberships, entity-scoped storage
constructive-sdk-uploads File uploads — presigned URL flow, bucket provisioning, upload-client, deduplication
constructive-starter-kits Project scaffolding — pgpm init templates, Next.js app boilerplate, custom template authoring
constructive-frontend UI components (50+ on Base UI + Tailwind v4), CRUD Stack cards, dynamic _meta forms
constructive-testing All test frameworks — pgsql-test, drizzle-orm-test, supabase-test, Drizzle ORM patterns, pgsql-parser
constructive-sdk-events Events & achievements — EventTracker blueprint node, blueprint achievements[], invite virality, achievement credit rewards
constructive-jobs Background jobs — JobTrigger blueprint node, payload strategies, Knative worker pipeline, scheduled jobs
constructive-sdk-ai AI capabilities — Search* blueprint nodes (SearchUnified, SearchVector), embedding worker pipeline, agentic-kit LLM client, RAG patterns
inquirerer-cli inquirerer CLI framework — interactive prompts, appStash, yanse colors, README formatting
graphile-search Unified search plugin internals — SearchAdapter, tsvector/BM25/trgm/pgvector adapters (team-level)
fbp Flow-Based Programming — types, spec, evaluator, graph editor

Commands

Package a skill for distribution

cd .agents/skills
zip -r {skill-name}.zip {skill-name}/

Skill Structure

.agents/skills/
  {skill-name}/
    SKILL.md              # Required: skill definition (keep under 500 lines)
    references/           # Optional: detailed documentation
      {topic}.md
  {skill-name}.zip        # Required: packaged for distribution

SKILL.md Format

Each skill requires a SKILL.md with YAML frontmatter:

---
name: {skill-name}
description: {Description with trigger phrases for when to use this skill}
compatibility: {Environment requirements}
metadata:
  author: constructive-io
  version: "1.0.0"
---

Required frontmatter fields:

  • name: Max 64 chars, lowercase + numbers + hyphens, must match directory name
  • description: Max 1024 chars, include trigger phrases

Optional frontmatter fields:

  • compatibility: Environment requirements (Node.js version, dependencies)
  • metadata: Key-value pairs (author, version)
  • license: License reference

Naming Conventions

  • Skill directory: kebab-case
  • SKILL.md: Always uppercase, exact filename
  • Zip file: Must match directory name: {skill-name}.zip

Key Design Principles

  • Skills are loaded on-demand (only name/description at startup, full SKILL.md when activated)
  • Keep SKILL.md under 500 lines; put detailed docs in references/ directory
  • Write specific descriptions with trigger phrases so agents know when to activate
  • Include "When to Apply" section in SKILL.md
  • Provide concrete code examples, not just descriptions