@a16njs/plugin-claude

Claude Code plugin for a16n. Discovers and emits Claude configuration.

Stability

As of 1.0.0, the plugin's discover/emit behavior and supported-type contract are stable and follow semantic versioning: breaking changes to the public API bump the major version.

Installation

This plugin is bundled with the a16n CLI. For programmatic use:

npm install @a16njs/plugin-claude

Supported Types

This plugin supports five customization types:

| Type | Claude Format | Description | |------|---------------|-------------| | GlobalPrompt | .claude/rules/*.md | Always-active instructions | | FileRule | .claude/rules/*.md with paths: frontmatter | Glob-triggered via native paths | | SimpleAgentSkill | .claude/skills/*/SKILL.md | Description-triggered skills | | AgentIgnore | .claude/settings.json permissions.deny | Files to exclude | | AgentCommand | Emitted only | Cursor commands become skills |

Note: Claude has no dedicated command concept. AgentCommands from Cursor are emitted as skills with a description enabling /command-name invocation. The Claude plugin never discovers AgentCommands—conversion is one-way (Cursor → Claude only).

Supported Files

Discovery

• CLAUDE.md - Root Claude configuration (GlobalPrompt)
• */CLAUDE.md - Nested Claude configuration files (GlobalPrompt)
• .claude/rules/*.md - Native Claude rules (GlobalPrompt if no paths:, FileRule if paths: present)
• .claude/skills/*/SKILL.md - Skills with description frontmatter (SimpleAgentSkill)
• .claude/settings.json - Permissions deny rules (AgentIgnore)

Note: Skills with hooks: in their frontmatter are skipped (not supported by AgentSkills.io). Note: Only Read() permission denials are discovered (other types like Bash() or Edit() are ignored).

Spec Compliance

a16n's IR is shaped after the AgentSkills.io specification. Claude is a large superset of that spec, so a Claude-only feature is a portability hazard on ingest no matter where the skill is being converted to. Skills using one are still discovered, with their content untouched — you get one approximated warning naming the features whose runtime behavior does not survive:

| Category | Features | |----------|----------| | Frontmatter keys | argument-hint:, arguments:, model:, effort:, context:, agent:, shell:, disallowed-tools:, user-invocable: | | Body substitutions | $ARGUMENTS, !`cmd` bash injection, ${CLAUDE_*} variables, @path file includes |

hooks: is deliberately absent from that list: it is skipped outright rather than advised. Losing a substitution leaves visibly broken output, but losing a PreToolUse hook leaves a clean-looking skill that no longer enforces what it claims to. Restriction-removing loss fails closed; substitution-breaking loss fails open.

paths: and disable-model-invocation: are also non-spec, but a16n models them natively, so they convert without a warning.

The spec's own optional fields — license, compatibility, metadata, and allowed-tools — are discovered and re-emitted verbatim, with no warning in either direction. Claude honors all four, so nothing is lost. They ride along on skills classified as SimpleAgentSkill, AgentSkillIO, and ManualPrompt; the last matters because a skill with disable-model-invocation: true becomes a ManualPrompt, and those are precisely the skills most likely to declare allowed-tools.

$1 positionals and $name named arguments are absent for a different reason: neither can appear in a skill that is not already warned about by $ARGUMENTS, arguments:, or argument-hint:. Reporting a loss is this warning's job; listing every construct in your body that depends on that loss would be linting your file. So the advisory names what will not survive, once.

Detection is otherwise conservative where Claude syntax collides with ordinary shell or prose: @ references need path shape, so @reviewer and @scope/pkg stay silent. The tradeoff is a known false negative on extensionless references like @src/utils, which are lexically identical to a scoped package name.

Emission

• GlobalPrompt → .claude/rules/<name>.md (individual files)
• FileRule → .claude/rules/<name>.md with paths: YAML frontmatter
• SimpleAgentSkill → .claude/skills/<name>/SKILL.md with description frontmatter
• AgentIgnore → .claude/settings.json with permissions.deny Read rules
• ManualPrompt → .claude/skills/<promptName>/SKILL.md with authored description when present, otherwise Invoke with /command

File Formats

.claude/rules/*.md (GlobalPrompt)

Rules without paths: frontmatter apply to all files:

## From: .cursor/rules/general.mdc

Your instructions for Claude here.

.claude/rules/*.md (FileRule)

Rules with paths: frontmatter apply only when working with matching files:

---
paths:
  - "**/*.tsx"
  - "**/*.jsx"
---

## From: .cursor/rules/react.mdc

Use functional components with hooks.

SKILL.md (SimpleAgentSkill)

---
description: Testing best practices
---

Write unit tests first.
Aim for 80% code coverage.

Usage

import claudePlugin from '@a16njs/plugin-claude';
import { A16nEngine } from '@a16njs/engine';

const engine = new A16nEngine([claudePlugin]);

// Discover Claude configuration
const result = await claudePlugin.discover('./my-project');
console.log(`Found ${result.items.length} items`);

// Emit to Claude format
await claudePlugin.emit(result.items, './my-project');

Documentation

Full documentation available at https://texarkanine.github.io/a16n/plugin-claude.