# Add Primitive

> Add or modify AI primitive definitions in the data layer with correct typing and complete metadata. Use when adding new primitives, updating descriptions, or extending primitive categories. Use when this capability is needed.

- Skill: `tomevault-io/add-primitive` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/add-primitive`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/add-primitive/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/add-primitive

---


# Add Primitive

Add or modify AI primitive definitions for agentconfig.org.

## Overview

Primitives appear in three places that must stay synchronized:
1. **Primitive Cards** - `site/src/data/primitives.ts`
2. **File Tree** - `site/src/data/fileTree.ts`
3. **Provider Comparison** - `site/src/data/comparison.ts`

## Step-by-Step Process

### 1. Define the Primitive

Edit `site/src/data/primitives.ts`:

```typescript
{
  id: 'your-primitive-id',           // lowercase, hyphens
  name: 'Display Name',
  description: 'One-sentence summary.',
  whatItIs: 'Detailed explanation of the concept.',
  useWhen: [
    'First use case',
    'Second use case',
  ],
  prevents: 'What problem/failure this prevents',
  combineWith: ['Other Primitive', 'Another Primitive'],
  implementations: [
    {
      provider: 'copilot',
      implementation: 'How Copilot implements this',
      location: '.github/path/to/file',
      support: 'full',  // 'full' | 'partial' | 'diy'
    },
    {
      provider: 'claude',
      implementation: 'How Claude implements this',
      location: '.claude/path/to/file',
      support: 'full',
    },
  ],
  category: 'instructions',  // 'instructions' | 'execution' | 'safety'
}
```

### 2. Add to File Tree (if applicable)

If the primitive has associated files, add nodes to both trees in `site/src/data/fileTree.ts`:

**For Copilot** - Add to `copilotTree`:
```typescript
{
  id: 'copilot-your-primitive',
  name: 'your-file.md',
  type: 'file',
  details: {
    label: 'Short Label',
    description: 'What this file does.',
    whatGoesHere: ['Content item 1', 'Content item 2'],
    whenLoaded: 'When this file is loaded.',
    loadOrder: 5,  // 1 = first loaded
    example: `Example content here`,
  },
}
```

**For Claude** - Add to `claudeTree` with equivalent structure.

### 3. Add to Comparison Matrix

Edit `site/src/data/comparison.ts`:

```typescript
{
  primitiveId: 'your-primitive-id',  // Must match primitives.ts
  primitiveName: 'Display Name',
  copilot: {
    level: 'full',  // 'full' | 'partial' | 'none'
    implementation: 'How Copilot does it',
    location: '.github/path',
  },
  claude: {
    level: 'full',
    implementation: 'How Claude does it',
    location: '.claude/path',
  },
}
```

## Data Types Reference

### Primitive Interface
```typescript
interface Primitive {
  id: string
  name: string
  description: string
  whatItIs: string
  useWhen: string[]
  prevents: string
  combineWith: string[]
  implementations: ProviderImplementation[]
  category: 'instructions' | 'execution' | 'safety'
}
```

### Provider Implementation
```typescript
interface ProviderImplementation {
  provider: 'copilot' | 'claude'
  implementation: string
  location: string
  support: 'full' | 'partial' | 'diy'
}
```

### Support Levels
- `full` - Native, well-documented support
- `partial` - Works but with limitations
- `diy` - Achievable with custom configuration

### Categories
- `execution` - Capability primitives (what it can do)
- `instructions` - Customization primitives (how to shape it)
- `safety` - Control primitives (guardrails and verification)

## Checklist

Before considering the primitive complete:

- [ ] Added to `primitives.ts` with all required fields
- [ ] Added to `fileTree.ts` for both Copilot and Claude (if has files)
- [ ] Added to `comparison.ts` with accurate support levels
- [ ] `id` is unique and matches across all three files
- [ ] `combineWith` references valid primitive names
- [ ] Examples in file tree are accurate and helpful
- [ ] Run `bun run typecheck` - No TypeScript errors
- [ ] Visually verify in all three site sections

## Common Mistakes

1. **Mismatched IDs** - The `id` in primitives.ts must match `primitiveId` in comparison.ts
2. **Missing file tree entries** - If the primitive has files, both trees need updates
3. **Stale combineWith** - Referencing primitives that don't exist
4. **Incorrect load order** - File tree `loadOrder` should reflect actual precedence
5. **Missing support level** - Every provider implementation needs a support level

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/agentconfig) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->