Agent Skills

Blocks Skills give AI coding agents the platform knowledge and verified workflows they need to build applications with Blocks OS.

Instead of repeatedly explaining Blocks APIs, authentication rules, request formats, and implementation patterns, you can install the skills and describe the outcome you want. The agent selects the relevant skill, follows its documented workflow, calls the appropriate Blocks APIs, and generates code based on verified API behavior.

Current support
Blocks Skills are currently developed and maintained for Claude Code. They use Markdown-based SKILL.md files and supporting resources that are loaded when a relevant task is detected.

View the Blocks Skills repository

What is an agent skill?

An agent skill is a focused package of instructions and supporting resources that teaches an AI agent how to perform a specific type of work.

A Blocks skill can provide:

• Guidance for deciding which workflow to use
• Verified Blocks OS API routes and request formats
• Authentication and project-selection rules
• Multi-step configuration and implementation flows
• Request and response contracts
• Error-handling and verification steps
• Framework-specific implementation examples
• Scripts for repeatable tasks such as project preflight checks

Skills are loaded only when they are relevant. This allows an agent to access detailed Blocks knowledge without placing every API rule and workflow into every conversation.

Why use Blocks Skills?

Blocks OS provides services for identity, data, localization, storage, communication, AI, monitoring, release management, and other application capabilities. Using these services directly requires developers and agents to understand service-specific APIs, authentication contexts, platform conventions, and dependencies between operations.

Blocks Skills make this easier by giving the agent reusable, task-oriented instructions.

Work from verified API behavior

The skills are grounded in calls made against the live Blocks v4 APIs. They document behavior that may not be obvious from an API specification alone, including served paths, actual response shapes, non-standard envelopes, endpoint casing, required headers, and API-specific quirks.

This reduces the risk of an agent inventing routes, fields, or request structures.

Follow complete workflows

Many Blocks tasks require multiple operations in the correct order. For example, configuring a project may require the agent to authenticate, identify the account tenant, select a project and environment, impersonate the project, perform the configuration, and verify the result.

A skill captures the complete workflow rather than documenting isolated API calls without context.

Generate consistent application code

Where applicable, skills include frontend references for the Blocks Construct React stack:

• React 19
• TypeScript
• Vite
• Tailwind CSS
• shadcn/ui
• TanStack Query
• Zustand

The API knowledge in the skills is not limited to this frontend stack, but the included React references provide a consistent default implementation.

Keep credentials and runtime authentication separate

Blocks Skills distinguish between administrative configuration and application runtime behavior. This helps prevent privileged project tokens or account credentials from being placed in browser code.

How Blocks Skills work

When you describe a Blocks-related task, Claude Code discovers the available skills and uses the description in each SKILL.md file to determine which skill is relevant.

Your request
    │
    ▼
Skill description and routing
    │
    ▼
Documented flow or procedure
    │
    ▼
Verified endpoints and contracts
    │
    ▼
Code generation or API execution
    │
    ▼
Verification of the result

A typical skill may contain the following files:

skills/blocks-<name>/
├── SKILL.md              # Purpose, routing, authentication, concepts, and gotchas
├── flows/                # Multi-step procedures and verification steps
├── scripts/              # Optional executable helpers
├── endpoints.md          # Exact request and response contracts, where required
└── references/
    └── react.md          # Typed React client, hooks, and implementation examples

Not every skill requires every file. Each skill is kept focused on one clear job.

Skills, agents, tools, and knowledge bases

These concepts serve different purposes:

Concept	Purpose
Agent	Understands the request, plans the work, and coordinates actions.
Skill	Teaches the agent how to perform a specific workflow or type of task.
Tool or MCP server	Gives the agent a live capability, such as calling a service, reading an external system, or performing an operation.
Knowledge base	Provides source material that the agent can search and use when answering questions.

A skill does not replace an API, tool, or permission. It tells the agent how to use the capabilities available to it correctly.

Configuration and implementation skills

Blocks work is divided into two important modes. The distinction determines how the agent authenticates and which credentials can be used.

Configuration

Configuration skills perform administrative operations on a Blocks project, such as:

• Creating schemas and fields
• Configuring SSO or OIDC
• Creating roles and permissions
• Managing project-level localization
• Creating or modifying project environments

These workflows authenticate an administrative user, select the intended project and environment, and obtain a project-scoped impersonated token. Configuration credentials and tokens must remain in local or server-side tooling and must never be placed in frontend code.

Implementation

Implementation skills generate or modify application code that runs as the signed-in user, such as:

• Running GraphQL CRUD operations
• Uploading and downloading files
• Adding SSO login to a frontend
• Loading localization resources
• Reading the current user's profile

Browser implementations use the public project key and the Blocks-hosted session flow. Privileged configuration tokens are not shipped to the browser.

Some IAM management skills support both modes. In those cases, the skill explicitly documents whether the operation is being performed by administrative tooling or by a signed-in application user.

Available skills

The public repository currently includes the following skills.

Getting started

Skill	Purpose
blocks-onboarding	Detect whether the user has an account, credentials, projects, and environments; guide signup where needed; create and manage projects and environments; and route the user to the appropriate Blocks skill.

Data

Skill	Mode	Purpose
blocks-data-gateway-configuration	Configuration	Create and edit schemas and fields, configure validation and access policies, reload schema changes, clean up mock data, and exchange schemas between projects.
blocks-data-gateway-crud	Implementation	Implement GraphQL create, read, update, and delete operations against schemas exposed through the Blocks Data runtime gateway.
blocks-data-storage	Implementation	Implement file and document management, including pre-signed uploads, downloads, folders, tags, versions, and deletion.

IAM and SSO

Skill	Mode	Purpose
blocks-iam-sso-oidc-configuration	Configuration	Create and configure the OIDC client and Blocks identity provider required by a project.
blocks-iam-sso-oidc-implementation	Implementation	Add the hosted Blocks authorization-code login flow, callback handling, cookie-based sessions, and session renewal to an application.
blocks-iam-account	Configuration or implementation	Activate invited users and implement logout and account-session actions.
blocks-iam-access-control	Configuration or implementation	Create and manage permissions and roles, and assign permissions to roles.
blocks-iam-users	Configuration or implementation	Create and manage users, retrieve the current user, view activity, and assign roles and permissions.
blocks-iam-organizations	Configuration or implementation	Create and manage organizations, list a user's organizations, and configure multi-organization behavior.

Localization

Skill	Mode	Purpose
blocks-localization-configuration	Configuration	Manage languages, feature modules, translation keys, and translations, and generate runtime localization files.
blocks-localization-implementation	Implementation	Load localization resources in an application, render content by translation key, and implement language switching.

Local development

Skill	Mode	Purpose
blocks-frontend-local-https	Development tooling	Run a frontend locally over HTTPS on its actual project domain so secure, domain-scoped Blocks session cookies work during SSO development.

Skill development

Skill	Purpose
skill-creator	Create, edit, evaluate, and improve skills in the Blocks Skills repository. This is contributor tooling rather than a Blocks product workflow.

Service naming
The skills target the Blocks v4 APIs. Some skill names retain familiar legacy terms for discoverability. In v4, IDP is IAM, Data Gateway or UDS is Data, and UILM is Localization.

Prerequisites

To use the skills, you need:

• A Blocks OS account
• Claude Code installed and authenticated
• A local application repository or working directory
• Git for downloading the skills repository
• Network access to the relevant Blocks OS services

Most configuration workflows also require:

• At least one Blocks project and environment
• A local .env file containing your Blocks API URL, username, and password
• Sufficient permissions for the requested project operation

The onboarding skill checks these prerequisites and guides you through missing setup.

Install the skills

Claude Code discovers project skills from .claude/skills/ in your repository. Installing skills at the project level allows the skill set to be shared with the team through version control.

Install all Blocks Skills for a project

From the root of your application repository, run:

git clone --depth 1 https://github.com/SELISEdigitalplatforms/blocks-skills.git /tmp/blocks-skills
mkdir -p .claude/skills
cp -R /tmp/blocks-skills/skills/. .claude/skills/
rm -rf /tmp/blocks-skills

For Windows PowerShell:

git clone --depth 1 https://github.com/SELISEdigitalplatforms/blocks-skills.git "$env:TEMP\blocks-skills"
New-Item -ItemType Directory -Force ".claude\skills" | Out-Null
Copy-Item "$env:TEMP\blocks-skills\skills\*" ".claude\skills" -Recurse -Force
Remove-Item "$env:TEMP\blocks-skills" -Recurse -Force

Review the copied files before committing them to your repository.

Install a selected skill

You may copy only the skills needed by your project. For example:

mkdir -p .claude/skills
cp -R /tmp/blocks-skills/skills/blocks-onboarding .claude/skills/
cp -R /tmp/blocks-skills/skills/blocks-data-gateway-crud .claude/skills/

Install blocks-onboarding when users may be new to Blocks or when account, credential, project, or environment prerequisites may be missing.

Install for your user account

To make the skills available across your local projects, copy them to:

~/.claude/skills/

Project-level installation is recommended for teams because it makes the selected skill versions visible and reviewable within the application repository.

Quick start

After installing the skills, start Claude Code from your application directory:

claude

Then describe the outcome you want. Claude can select the relevant skill automatically.

I'm new to Blocks. Check what I need and help me set up a development project.

Create a Product schema with title, price, description, and tags, then reload it.

Add typed CRUD operations for the Product schema to this React application.

Configure SSO for this project and add the login flow to the frontend.

Add Bengali and German translations for the login page and create a language switcher.

Run this Vite application locally over HTTPS on its Blocks project domain.

You can also invoke an installed skill directly using its skill name, for example:

/blocks-onboarding

Credential and security guidance

Skills may instruct the agent to run scripts, call APIs, or modify application code. Review the skill source and the proposed action before approving sensitive operations.

Follow these rules when working with Blocks Skills:

• Create the credential .env file yourself; do not paste passwords into an agent conversation.
• Add .env to .gitignore before running configuration workflows.
• Never commit account passwords, refresh tokens, or impersonated project tokens.
• Never place privileged tokens in VITE_, NEXT_PUBLIC_, or other client-exposed environment variables.
• Treat the Blocks project key as a public project identifier, not as an authorization secret.
• Keep configuration credentials and impersonated tokens in local or server-side tooling.
• Review generated code and API mutations before deploying them to production.
• Use a development project or environment when evaluating a skill for the first time.
• Grant users and agents only the permissions required for the intended workflow.

Skills do not bypass Blocks OS access control. API operations still succeed or fail according to the authenticated user's roles, permissions, project access, and environment configuration.

Operations that may require manual action

Most project operations documented by the skills can be performed through the Blocks APIs. Some steps still require user interaction, including:

• Creating a Blocks OS account
• Completing CAPTCHA-protected or browser-only account flows
• Resetting a forgotten password
• Trusting a local HTTPS certificate on the operating system
• Reviewing or approving destructive changes

The agent should explain the required manual step and verify the result before continuing.

Keep skills up to date

Blocks APIs and recommended implementation patterns can change. Periodically review the public repository and update the skill folders installed in your project.

When updating:

1. Review the repository changes.
2. Replace or merge the affected skill folders.
3. Check for changes to authentication, environment variables, routes, and request contracts.
4. Test the updated workflow in a development environment.
5. Commit the updated skills with the application so the team uses the same version.

Contributing

Blocks Skills are open source under the MIT License. Contributions should be based on verified API behavior rather than assumptions made from Swagger or older documentation.

Useful contributions include:

• New focused Blocks service skills
• Verified multi-step workflows
• Corrections to endpoint or response contracts
• Additional framework references
• Better error handling and verification instructions
• Reproductions and documentation of platform-specific behavior

Before contributing, read the repository's contribution guide and follow its verification and scope requirements.

• View the source repository
• Read the contribution guide
• Report an issue