Skip to content
Skills Library
Programming · Building & coding

secondbrain-entity

/secondbrain-entity

This skill should be used when the user asks to "add entity", "create custom entity", "new entity type", "define entity", or mentions wanting to add a new trackable data type to their secondbrain project beyond the predefined ADR, Note, Task, and Discussion types.

Repository
ai ↗
Licence
Unlicense
Last repository change
17.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.08.2026, without references to retired models or APIs.

Licence

Unlicense, otwarta.

What it does and when to use it

This skill should be used when the user asks to "add entity", "create custom entity", "new entity type", "define entity", or mentions wanting to add a new trackable data type to their secondbrain project beyond the predefined ADR, Note, Task, and Discussion types.

Triggers from the description

add entitycreate custom entitynew entity typedefine entity
Original author description

This skill should be used when the user asks to "add entity", "create custom entity", "new entity type", "define entity", or mentions wanting to add a new trackable data type to their secondbrain project beyond the predefined ADR, Note, Task, and Discussion types.

How it works

  1. Prerequisites
  2. Workflow
  3. Field Types
  4. ID Formats
  5. Tips
Original SKILL.md headings · 274 lines, 754 words
SKILL.md preview
---
name: secondbrain-entity
description: |
  This skill should be used when the user asks to "add entity", "create custom entity",
  "new entity type", "define entity", or mentions wanting to add a new trackable data type
  to their secondbrain project beyond the predefined ADR, Note, Task, and Discussion types.
---

# Add Custom Entity

Create custom entity types with schema validation and VitePress integration.

## Prerequisites

Verify secondbrain is initialized:
1. Check for `.claude/data/config.yaml`
2. If not found, suggest running `secondbrain-init` first

## Workflow

### Step 1: Gather Entity Information

Collect from user:

1. **Entity Name** — Plural name (e.g., "contacts", "projects", "bookmarks")
2. **Singular Name** — For display (e.g., "contact", "project", "bookmark")
3. **Fields** — Custom fields for the entity:
   - Field name (snake_case)
   - Field type (string, integer, boolean, date, array, enum)
   - Required or optional
   - For enums: allowed values
4. **ID Format** — How records are numbered/identified:
   - Sequential (`PREFIX-XXXX`)
   - Date-based (`YYYY-MM-DD-slug`)
   - UUID
5. **Status Workflow** (optional) — If entity has status tracking

### Step 2: Generate Schema

Create `.claude/data/<entity>/schema.yaml`:

```yaml
type: object
required: [records]
properties:
  last_number:
    type: integer
    description: Last assigned sequential number
  records:
    type: array
    items:
      type: object
      required: [id, title, created, file]
      properties:
        id:
          type: string
          description: Unique identifier
        title:
          type: string
          description: Display title
        created:
          type: string
          format: date
        file:
          type: string
          description: Path to markdown file
        status:
          type: string
          enum: [active, archived]
        # ... custom fields
```

### Step 3: Initialize Records File

Create `.claude/data/<entity>/records.yaml`:

```yaml
last_number: 0
records: []
```

### Step 4: Create Document Template

Create `templates/entities/<entity>/TEMPLATE.md`:

```markdown
---
id: {{id}}
title: {{title}}
created: {{date}}
status: active
# ... custom fields
---

# {{title}}

## Overview

[Description]

## Details

[Content]
```

### Step 5: Create VitePress Data Loader

Create `docs/.vitepress/data/<entity>.data.ts`:

```typescript
import { defineLoader } from 'vitepress'
import fs from 'fs'
import yaml from 'js-yaml'

interface Record {
  id: string
  title: string
  created: string
  file: string
  status: string
  // ... custom fields
}

export interface Data {
  records: Record[]
  lastNumber: number
}

declare const data: Data
export { data }

export default defineLoader({
  watch: ['.claude/data/<entity>/*.yaml'],
  async load(): Promise<Data> {
    const recordsPath = '.claude/data/<entity>/records.yaml'

    if (!fs.existsSync(recordsPath)) {
      return { records: [], lastNumber: 0 }
    }

    const content = fs.readFileSync(recordsPath, 'utf-8')
    const parsed = yaml.load(content) as any

    return {
      records: parsed.records || [],
      lastNumber: parsed.last_number || 0
    }
  }
})
```

### Step 6: Create Documentation Index

Create `docs/<entity>/index.md`:

```markdown
---
title: <Entity> Index
---

# <Entity>

<script setup>
import { data } from '../.vitepress/data/<entity>.data'
import EntityTable from '../.vitepress/theme/components/EntityTable.vue'

const columns = [
  { key: 'id', label: 'ID', sortable: true },
  { key: 'title', label: 'Title', sortable: true },
  { key: 'created', label: 'Created', sortable: true },
  { key: 'status', label: 'Status', sortable: true }
]
</script>

<EntityTable :data="data.records" :columns="columns" />
```

### Step 7: Update Configuration

Add entity to `.claude/data/config.yaml`:

```yaml
entities:
  <entity>:
    enabled: true
    singular: <singular>
    id_format: sequential  # or date-based, uuid
    prefix: PREFIX         # for sequential IDs
    freshness:
      stale_after_days: 30
    fields:
      - name: field_name
        type: string
        required: true
```

### Step 8: Update Sidebar

Add to `docs/.vitepress/config.ts` sidebar:

```typescript
{
  text: '<Entity>',
  collapsed: true,
  items: [
    { text: 'Overview', link: '/<entity>/' }
  ]
}
```

### Step 9: Confirm Creation

```
## Entity Created

**Name:** <entity>
**Singular:** <singular>
**ID Format:** sequential (PREFIX-XXXX)
**Status Tracking:** Yes

### Fields
| Field | Type | Required |
|-------|------|----------|
| title | string | Yes |
| description | string | No |
| priority | enum (low, medium, high) | No |

### Files Created
- `.claude/data/<entity>/schema.yaml`
- `.claude/data/<entity>/records.yaml`
- `docs/.vitepress/data/<entity>.data.ts`
- `docs/<entity>/index.md`

### Next Steps
1. Create records using the new entity type
2. Add entity-specific skills if needed
3. Customize the index page layout
```

## Field Types

| Type | YAML Schema | Example |
|------|-------------|---------|
| string | `type: string` | "Hello world" |
| integer | `type: integer` | 42 |
| number | `type: number` | 3.14 |
| boolean | `type: boolean` | true/false |
| date | `type: string, format: date` | 2026-01-15 |
| datetime | `type: string, format: date-time` | 2026-01-15T10:30:00Z |
| array | `type: array, items: {...}` | [tag1, tag2] |
| enum | `type: string, enum: [...]` | "active" |

## ID Formats

### Sequential
Best for: Tasks, tickets, numbered records
```
PREFIX-0001, PREFIX-0002, PREFIX-0003
```

### Date-based
Best for: Notes, journal entries, time-sensitive content
```
2026-01-15-meeting-notes
2026-01-15-architecture-review
```

### UUID
Best for: Globally unique, import/export scenarios
```
550e8400-e29b-41d4-a716-446655440000
```

## Tips

1. **Keep fields minimal** — Start with essential fields, add more later
2. **Use enums for fixed values** — Better than free-form strings
3. **Consider status workflow** — Most entities benefit from status tracking
4. **Plan ID format carefully** — Hard to change after records exist
5. **Reuse existing patterns** — Look at ADR, Task, Note for inspiration
Files in this package (2)
  • SKILL.md 6 KB
  • references/entity-schemas.md 8 KB

Versions

The database has no other skills named secondbrain-entity.

Database snapshot: 13.11.2026 · package version 2019240a71eb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100secondbrain-search-init
    This skill should be used when the user asks to "initialize search", "set up semantic search", "enable qmd", "add search to secondbrain", or mentions wanting to enable semantic search capabilities for an existing secondbrain project.
  • 100secondbrain-adr
    This skill should be used when the user asks to "create ADR", "document decision", "architecture decision", "add decision record", or mentions needing to record a technical decision with status tracking and category organization.
  • 100ha-entity-lifecycle
    Entity lifecycle and device/entity registries in Home Assistant. Use when asking about entity registration, async_added_to_hass, async_will_remove_from_hass, device_info, identifiers, or restoring previous state.
  • 100general-create-workspace
    Create a new workspace for an entity in the Umbraco backoffice. Supports two workspace types — default (simple, manifest-only, for root/listing pages) and routable (entity detail editing with create/edit flows). Use when the user says "create a workspace", "add a workspace for…
  • 100add-entity
    Add a new first-class entity (table + model + repo + service + view) to the Personal Finance Manager. Use when adding something like PPF accounts, insurance policies, rental properties, or any new tracked record type that needs its own table and tab. Also use when reviewing…
  • 100model-entity-validator
    This skill should be used when the user asks to "create a model", "add a Django model", "create database table", "add entity", "define schema", or when writing class definitions inheriting from models.Model. Validates BaseModel inheritance pattern.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.