sidebar_position: 5 title: Claude Adapter description: Internal documentation for the Claude adapter generated from packages/skills.

Claude Adapter

This page documents the Claude-specific adapter built from packages/skills. It is not a standalone package anymore.

📦 Package Overview

Source package: packages/skills/
Build script: packages/skills/scripts/build-claude-adapter.js
Purpose: Package shared n8n instructions as a Claude Agent Skill
Type: Generated distribution artifact, not a published npm package
Source of truth: AiContextGenerator.getSkillContent()

🏗️ Architecture

Source And Output Structure

packages/skills/
├── src/services/ai-context-generator.ts
├── scripts/build-claude-adapter.js
├── dist/adapters/claude/
│   ├── n8n-architect/
│   │   ├── SKILL.md
│   │   └── README.md
│   └── install.sh
└── package.json

Build Output

packages/skills/dist/adapters/claude/
├── n8n-architect/
│   ├── SKILL.md
│   └── README.md
└── install.sh

The build also mirrors SKILL.md into the repository plugin tree under plugins/claude/n8n-as-code/skills/n8n-architect/.

🔧 Development

Building the adapter

cd packages/skills
npm run build:adapters

This:

Loads the compiled AiContextGenerator from dist/
Generates SKILL.md via getSkillContent()
Writes the Claude distribution files into dist/adapters/claude/
Mirrors the skill into the plugin distribution tree

From the workspace root, the compatibility entrypoint is:

npm run build:claude-plugin

What is actually generated

The builder writes:

packages/skills/dist/adapters/claude/n8n-architect/SKILL.md
packages/skills/dist/adapters/claude/n8n-architect/README.md
packages/skills/dist/adapters/claude/install.sh
plugins/claude/n8n-as-code/skills/n8n-architect/SKILL.md

There is no separate validate.js or hand-maintained template directory in the current implementation.

Local verification

cd packages/skills
npm run build
npm run build:adapters

Then inspect the generated files in dist/adapters/claude/ and verify that SKILL.md contains the current shared guidance.

Testing Locally

cd packages/skills
npm run build
npm run build:adapters
cd dist/adapters/claude
./install.sh

That installs n8n-architect into ~/.claude/skills/ for Claude Code. For hosted Claude flows, zip the generated n8n-architect/ directory.

📝 SKILL.md Format

The generated file must follow Anthropic's skill format:

---
name: n8n-architect              # lowercase, hyphens, max 64 chars
description: Expert assistant... # max 1024 chars, explains WHEN to use
---

# n8n Architect

## Instructions
[Markdown content with instructions for Claude]

## Examples
[Usage examples]

Content Guidelines

DO:

Reuse content from AiContextGenerator.getSkillContent()
Use npx n8nac skills (via the n8nac unified CLI)
Provide concrete examples in bash code blocks
Keep instructions imperative and clear

DON'T:

Invent parameters or hallucinate capabilities
Remove YAML frontmatter
Use vague language
Add commands not supported by n8nac skills

🔄 Content Consistency

The adapter is derived from the same source used for agent context generation. In practice:

// packages/skills/src/services/ai-context-generator.ts
public getSkillContent(distTag?: string): string {
  // Builds Claude skill content from shared command references and guidance
}

This keeps AGENTS.md and the Claude adapter aligned around the same workflow rules, command forms, and TypeScript examples.

📦 Distribution

Repository distribution

The generated adapter lives in the repository output tree and plugin tree. It can be zipped for Claude-compatible distribution, but it is not versioned as its own npm package.

Release relationship

Changes to Claude instructions should usually be treated as changes to @n8n-as-code/skills, because that package owns the generator and build script.

🧪 Testing Checklist

Before releasing:

[ ] cd packages/skills && npm run build succeeds
[ ] cd packages/skills && npm run build:adapters succeeds
[ ] Generated SKILL.md has valid YAML frontmatter
[ ] Test in Claude.ai (upload ZIP)
[ ] Test in Claude Code (local install)
[ ] Verify NPX commands execute correctly
[ ] Confirm generated guidance still matches current n8nac skills commands

🔧 Scripts Reference

`cd packages/skills && npm run build`

Compiles the package and copies JSON assets into dist/assets/.

`cd packages/skills && npm run build:adapters`

Generates the Claude adapter distribution files.

`npm run build:claude-plugin`

Workspace-level convenience script that builds the Skills package and its Claude adapter.

🚀 Release Process

The adapter follows the Skills package lifecycle:

Make changes to packages/skills/src/services/ai-context-generator.ts or packages/skills/scripts/build-claude-adapter.js
Commit with a conventional message so CI can infer the bump level
Push to next for prerelease validation
Merge next into main and let the release PR apply the final version bump

📚 Key Dependencies

n8nac: The unified CLI that exposes @n8n-as-code/skills commands via npx n8nac skills
@n8n-as-code/skills: Owns the shared generator and command surface
Node.js: Required for build and NPX execution

🐛 Common Issues

Adapter content is stale

Rebuild packages/skills before build:adapters
Check whether the source change was made in AiContextGenerator rather than a generated file

Generated files do not match the current CLI

Verify the command examples still use npx --yes n8nac skills
Check packages/skills/tests/ai-context-generator.test.ts for the expected canonical forms

Skill not recognized by Claude

Verify YAML name field matches reference
Check description explains WHEN to use
Ensure SKILL.md is in root of distribution folder

📖 References

🤝 Contributing

To improve this package:

Understand the Claude Agent Skills spec
Edit the shared generator in packages/skills/src/services/ai-context-generator.ts
Run cd packages/skills && npm run build && npm run build:adapters
Test in Claude.ai or Claude Code
Commit with a conventional message and submit PR

See Contribution Guide for general guidelines.

Adaptateur Claude