---

name: ai-instructions description: Set up shared .ai/ instruction infrastructure for multi-tool LLM workflows (Claude Code, Cursor, etc.) version: 1.0.0 user-invocable: true allowed-tools: Read, Write, Edit, Glob, Grep, Bash argument-hint: "[context|skills|full]"

Skill: AI Instructions Setup

Set up a shared .ai/ instruction directory in a project so that LLM context, conventions, and reusable task prompts are tool-agnostic and work across Claude Code, Cursor, Windsurf, and future tools.

Usage

• /ai-instructions — full setup: scaffold .ai/, wire CLAUDE.md, create Cursor adapter, add Makefile target
• /ai-instructions context — only create .ai/context/ with architecture + conventions files
• /ai-instructions skills — only create .ai/skills/ with an example skill template
• /ai-instructions full — full setup (same as no argument)

Instructions

When invoked, do the following:

1. Assess the project

Read the project root to understand what already exists:

• Check for existing CLAUDE.md, .cursorrules, .cursor/rules/, .ai/
• Check for Makefile (to add sync target)
• Identify the project's language/framework (read mix.exs, package.json, Cargo.toml, go.mod, etc.)
• Check .gitignore for relevant entries

Do not overwrite existing files. Merge into them or ask the user.

2. Create the .ai/ directory structure

.ai/
├── context/
│   ├── architecture.md    ← project structure, tech stack, key dependencies
│   └── conventions.md     ← coding standards, patterns, anti-patterns
└── skills/
    └── _template.md       ← reusable task prompt template (also serves as example)

Skills in .ai/skills/ are the canonical location. Both Claude Code and Cursor can reference them via @. For Cursor to discover them as /slash-commands, they also need to exist in .cursor/skills/ — the sync-ai target handles this (see step 5).

.ai/context/architecture.md

Auto-generate from what you can observe in the project. Include:

• Language/framework and versions
• Directory structure overview (high-level, not exhaustive)
• Key dependencies and what they're for
• Database, cache, message broker if applicable
• Deployment target if obvious (Fly.io, AWS, etc.)

Format:

# Architecture

## Tech Stack
- **Language:** [language and version]
- **Framework:** [framework and version]
- **Database:** [database and ORM/driver]

## Project Structure
- `src/` — application code
- `test/` — test suite
- ...

## Key Dependencies
- [dep] — [what it's for]
- ...

Keep it factual and derived from the code. Don't speculate.

.ai/context/conventions.md

Start with a minimal template the user can fill in:

# Conventions

## Code Style
<!-- Add project-specific conventions here -->
<!-- Examples: naming patterns, module organization, test patterns -->

## Patterns to Follow
<!-- Document patterns that are established in this codebase -->

## Anti-patterns to Avoid
<!-- Document things that have caused problems -->

If you can observe clear conventions from the code (e.g., consistent naming, test organization, formatter config), pre-populate them.

Always include an "AI Instructions" section in conventions.md that tells contributors to keep the sync in place:

## AI Instructions

- `.ai/` is the single source of truth for project context and skills shared across LLM tools
- **Context** lives in `.ai/context/` — architecture, conventions, etc.
- **Skills** live in `.ai/skills/<name>/SKILL.md` — reusable task prompts available as `/slash-commands`
- After editing `.ai/context/` or `.ai/skills/`, run `make sync-ai` to update `.cursor/` (rules and skills)
- Commit the synced `.cursor/` files alongside your `.ai/` changes

.ai/skills/_template/SKILL.md

Create an example skill template at .ai/skills/_template/SKILL.md:

---
name: skill-name
description: One-line description of what this skill does
---

# Skill: [Name]

## When to use
<!-- Describe the task this skill helps with -->

## Steps
<!-- Numbered steps the LLM should follow -->

## Example
<!-- Show what good output looks like -->

Skills use the <name>/SKILL.md directory convention so both Claude Code and Cursor can discover them as /slash-commands. The sync-ai target copies .ai/skills/*/SKILL.md into .cursor/skills/ for Cursor discovery.

3. Wire up CLAUDE.md

If CLAUDE.md exists, append @-imports at an appropriate location:

## Shared Context

@.ai/context/architecture.md
@.ai/context/conventions.md

If CLAUDE.md doesn't exist, create one with the imports and a minimal project section.

Important: Don't duplicate content that's already in CLAUDE.md. If CLAUDE.md already has architecture info, reference it from .ai/context/architecture.md instead of duplicating.

4. Create Cursor adapter

Rules

Create .cursor/rules/project.mdc that inlines the shared context:

---
description: Project context and conventions (auto-generated from .ai/)
globs:
alwaysApply: true
---

<!-- Auto-generated by `make sync-ai` from .ai/context/. Do not edit directly. -->

The actual content is generated by make sync-ai (see step 5), which concatenates .ai/context/*.md into this file.

Note: If the project already uses .cursorrules (legacy) or has existing .cursor/rules/*.mdc files, migrate their content into .ai/context/ and remove the originals. The project.mdc replaces them.

Skills

Cursor discovers skills from .cursor/skills/<name>/SKILL.md. The sync-ai target symlinks or copies .ai/skills/ entries into .cursor/skills/ so they're available as /slash-commands in Cursor. No manual setup needed — just put skills in .ai/skills/ and run make sync-ai.

5. Add Makefile sync target (if Makefile exists)

Append to existing Makefile:

# ── AI instruction sync ──────────────────────────────────────
sync-ai:       ## Sync .ai/ into .cursor/ (rules from context, skills from skills)
	@echo "Syncing .ai/context/ → .cursor/rules/project.mdc"
	@mkdir -p .cursor/rules .cursor/skills
	@echo '---' > .cursor/rules/project.mdc
	@echo 'description: Project context and conventions (auto-generated from .ai/)' >> .cursor/rules/project.mdc
	@echo 'globs:' >> .cursor/rules/project.mdc
	@echo 'alwaysApply: true' >> .cursor/rules/project.mdc
	@echo '---' >> .cursor/rules/project.mdc
	@echo '' >> .cursor/rules/project.mdc
	@cat .ai/context/*.md >> .cursor/rules/project.mdc
	@if [ -d .ai/skills ]; then \
		for skill in .ai/skills/*/SKILL.md; do \
			[ -f "$$skill" ] || continue; \
			name=$$(basename $$(dirname "$$skill")); \
			mkdir -p ".cursor/skills/$$name"; \
			cp "$$skill" ".cursor/skills/$$name/SKILL.md"; \
			echo "  Synced skill: $$name"; \
		done; \
	fi
	@echo "Done."

If no Makefile exists, skip this step and mention the manual alternative.

6. Update .gitignore

Ensure these are NOT ignored (they should be committed):

• .ai/
• .cursor/rules/
• .cursor/skills/
• CLAUDE.md

7. Report to the user

Summarize what was created:

AI instructions set up:

  .ai/context/architecture.md  ← auto-generated from project analysis
  .ai/context/conventions.md   ← template for team conventions
  .ai/skills/_template.md      ← reusable task prompt template
  CLAUDE.md                    ← updated with @-imports
  .cursor/rules/project.mdc   ← Cursor context (generated)
  .cursor/skills/              ← Cursor skills (synced from .ai/skills/)
  Makefile                     ← sync-ai target added

Next steps:
  1. Review .ai/context/architecture.md — verify it's accurate
  2. Fill in .ai/context/conventions.md with your team's patterns
  3. Add skills to .ai/skills/<name>/SKILL.md — they'll sync to Cursor via `make sync-ai`
  4. Run `make sync-ai` after editing .ai/ files to update Cursor

Design Principles

• CLAUDE.md is the primary source of truth — it's the most expressive format and Claude Code is the most capable tool
• .ai/ is the tool-agnostic layer — both Claude Code and Cursor users can reference these files
• Thin adapters, not duplicates — .cursor/rules/ should reference or sync from .ai/, not maintain separate content
• Skills live in .ai/skills/ — both Claude Code and Cursor support the <name>/SKILL.md convention. make sync-ai copies them to .cursor/skills/ for Cursor discovery
• Structure emerges from use — start minimal, add files as the team writes them. Don't pre-create empty directories or placeholder files beyond the template
• Don't over-organize — three files beats ten. A domain.md or testing.md can be added later when there's enough content to warrant it