Skip to content

AGENTS.md

Latest commit

 

History

History
144 lines (103 loc) · 5.69 KB

AGENTS.md

File metadata and controls

144 lines (103 loc) · 5.69 KB

This file originated from https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md and has been modified for this repository.

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.

Repository Overview

A collection of skills for AI coding agents working with Constructive tooling. Skills are organized into 10 umbrella skills that consolidate related functionality:

Skill Absorbs Purpose
constructive safegres, services-schemas, deployment, server-config, functions, cnc-execution-engine, constructive-env Platform core
pgpm github-workflows-pgpm Database migrations, CLI, Docker, CI/CD
constructive-graphql graphql-codegen, sdk-search, graphql-query Codegen, runtime queries, search, pagination
constructive-starter-kits boilerplate-pgpm-init, boilerplate-nextjs-app, boilerplate-authoring Project scaffolding via pgpm init
constructive-frontend constructive-ui, crud-stack, meta-forms UI components, Stack cards, dynamic forms
constructive-testing pgsql-test, drizzle-orm-test, supabase-test, drizzle-orm, pgsql-parser-testing All test frameworks
constructive-ai pgvector-rag, github-workflows-ollama RAG pipelines, embeddings, Ollama CI
constructive-tooling constructive-pnpm, inquirerer-cli, readme-formatting Dev tools
graphile-search (standalone) Unified search plugin internals (team-level)
fbp fbp-types, fbp-spec, fbp-evaluator, fbp-graph-editor Flow-Based Programming toolkit

Each umbrella skill has a SKILL.md router and a references/ directory with detailed topic-specific documentation.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    scripts/              # Required: executable scripts
      {script-name}.sh    # Bash scripts (preferred)
  {skill-name}.zip        # Required: packaged for distribution

Naming Conventions

  • Skill directory: kebab-case (e.g., constructive-codegen, log-monitor)
  • SKILL.md: Always uppercase, always this exact filename
  • Scripts: kebab-case.sh (e.g., deploy.sh, fetch-logs.sh)
  • Zip file: Must match directory name exactly: {skill-name}.zip

SKILL.md Format

---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases like "Deploy my app", "Check logs", etc.}
---

# {Skill Title}

{Brief description of what the skill does.}

## How It Works

{Numbered list explaining the skill's workflow}

## Usage

```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]

Arguments:

  • arg1 - Description (defaults to X)

Examples: {Show 2-3 common usage patterns}

Output

{Show example output users will see}

Present Results to User

{Template for how agent should format results when presenting to users}

Troubleshooting

{Common issues and solutions, especially network/permissions errors}


### Best Practices for Context Efficiency

Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:

- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
- **Write specific descriptions** — helps the agent know exactly when to activate the skill
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files

### Reference Documentation

The `references/` directory contains detailed documentation split into focused sections for selective reading by agents. This minimizes token usage by allowing agents to read only what's needed for the specific task.

**Structure:**

skills/ {skill-name}/ SKILL.md references/ {topic-1}.md # Focused documentation on specific topic {topic-2}.md # Another focused topic


**Best Practices:**
- **Split by topic** — separate concerns into individual files (e.g., `cli-reference.md`, `hooks-patterns.md`, `error-handling.md`)
- **Clear naming** — file names should indicate exactly what content they contain
- **Reference from SKILL.md** — list all reference files with brief descriptions so agents know which to read
- **Selective reading** — agents should read only the relevant reference files for their current task
- **Keep focused** — each reference file should cover one specific aspect (API, patterns, configuration, etc.)

**Example:**
If a skill generates both hooks and ORM code, split references into:
- `hooks-output.md` - API reference for generated hooks
- `hooks-patterns.md` - Usage patterns and examples for hooks
- `orm-output.md` - API reference for generated ORM
- `orm-patterns.md` - Usage patterns and examples for ORM
- `config-reference.md` - Configuration options

This allows agents helping with ORM queries to read only `orm-patterns.md` instead of loading all documentation.

### Script Requirements

- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`

### Creating the Zip Package

After creating or updating a skill:

```bash
cd skills
zip -r {skill-name}.zip {skill-name}/