Extend Flint with skills, templates, and automation.

Purpose

Flint's core is intentionally minimal - a workspace structure and indexing. Everything else comes from shards: project management workflows, increment tracking, planning systems, notepad capture.

Shards are markdown-based prompt packages. They provide context (init files that agents load), skills (repeatable tasks), templates (document structures), workflows (multi-step processes), and knowledge (deep reference material). Installing a shard gives your Flint - and the agents working in it - new capabilities.

The shard system is designed for AI agents. Shards don't run code; they provide structured prompts that agents interpret. This makes shards portable, inspectable, and safe.

Shard Structure

Each shard lives in Shards/[Name]/ and follows a standard structure:

Shards/
├── Projects/                   # Task management
│   ├── shard.yaml             # Shard manifest (required)
│   ├── init-proj.md           # Context for agents
│   ├── skills/
│   │   ├── sk-proj-capture_as_task.md
│   │   └── sk-proj-archive_tasks.md
│   ├── templates/
│   │   └── tmp-proj-task.md
│   ├── workflows/
│   │   ├── wkfl-proj-create_task.md
│   │   └── wkfl-proj-do_task.md
│   ├── knowledge/
│   │   └── knw-proj-conventions.md
│   ├── scripts/
│   │   └── newtasknum.js
│   └── install/
│       └── (Dashboard) Backlog.md
├── Increments/                 # Version tracking
│   ├── shard.yaml
│   ├── init-inc.md
│   ├── skills/
│   │   ├── sk-inc-complete.md
│   │   ├── sk-inc-consolidate.md
│   │   ├── sk-inc-iterate.md
│   │   └── sk-inc-sync.md
│   └── templates/
│       └── tmp-inc-stream.md
└── (Dev) My Shard/             # Local dev shard
    ├── shard.yaml
    ├── .git/                   # Dev shards have git repos
    └── init-ms.md

File Types

Shard Manifest (shard.yaml)

Every shard has a shard.yaml that defines its identity and requirements:

version: "1.0.0"
name: Projects
shorthand: proj
description: High-level planning and task management

depends:
  - "NUU-Cognition/shard-flint"

install:
  - source: (Dashboard) Backlog.md
    dest: Mesh/(Dashboard) Backlog.md
    once: true              # Only install if file doesn't exist (default)
  - source: (Dashboard) Tasks.md
    dest: Mesh/(Dashboard) Tasks.md
    force: true             # Overwrite on every install/sync

folders:
  - Mesh/Types/Tasks/
  - Mesh/Archive/Tasks/

repos:
  - name: project-templates
    url: https://github.com/user/project-templates.git
    branch: main

state: true                 # Create state file in Mesh/Shards/

Key fields:

• version: Semantic version string
• shorthand: Short identifier used in file naming (e.g., proj)
• depends: Other shards that must be installed first (supports owner/repo format)
• install: Files to copy into the mesh from the shard's install/ folder
  • once: true (default) - Only install if target doesn't exist
  • force: true - Overwrite on every install/sync (preserves frontmatter IDs)
• folders: Directories to create on install
• repos: Git repositories to clone into Shards/(System) Repos/
• state: If true, creates a state file at Mesh/Shards/(Shard) [Name].md

Install entries support template variables: {{uuid}} (random UUID) and {{date}} (current date).

Installing Shards

From GitHub

flint shard install NUU-Cognition/shard-projects
flint shard install github:owner/repo

This clones the shard repository, reads shard.yaml, and:

1. Auto-installs any dependencies (circular deps prevented)
2. Creates the shard folder with all files
3. Creates declared folders in Mesh/
4. Installs files from install/ with template processing
5. Clones declared repos to Shards/(System) Repos/
6. Creates state file if configured
7. Adds declaration to flint.toml

From Local Path

flint shard install path:./Shards/(Dev) My Shard

Force Install

Use --force to overwrite existing files:

flint shard install NUU-Cognition/shard-projects --force

Listing Shards

Installed Shards

flint shard list

Shows shards installed in this flint with their versions. Dev shards are marked with (dev):

Installed shards:

  NAME              VERSION
  Projects          1.0.0
  Increments        1.0.0
  My Shard          0.1.0   (dev)

Source Declarations

flint shard list --sources

Shows shard source declarations from flint.toml.

Updating Shards

flint shard update

Checks remote versions via GitHub API and reinstalls shards that have updates. Dev shards (dev: true) are skipped. Uses --reinstall to force re-download all.

Uninstalling Shards

flint shard uninstall <name>

Removes the shard folder, installed files, declared folders (if empty), declared repos, and the flint.toml declaration.

Dev Shards (Local Authoring)

You can author new shards directly inside a Flint workspace. Dev shards are tracked in flint.toml with dev = true so that sync and update leave them alone.

Scaffolding a New Shard

flint shard create "My Shard" -s ms -d "My custom shard"

This creates Shards/(Dev) My Shard/ with the standard directory structure and records it in flint.toml:

[shards]
my-shard = { source = "path:./Shards/(Dev) My Shard", dev = true }

Options: --shorthand/-s, --description/-d, --setup (include setup file), --state (create state file).

Cloning an Existing Shard for Dev

To fork an existing shard for local editing:

flint shard dev NUU-Cognition/shard-projects

This copies the resolved shard into Shards/(Dev) Name/ with dev = true.

Dev Shard Git Integration

Dev shards can be version-controlled independently:

# Initialize git for a dev shard
flint shard gitinit my-shard https://github.com/org/repo.git

# Push changes
flint shard push my-shard -m "Add new skill"

Dev Shard Behavior

• Sync skips dev shards - locally managed, flint sync won't overwrite
• Update skips dev shards - flint shard update only updates non-dev shards
• List shows (dev) label - clearly distinguished in output
• (Dev) folder prefix - visually signals local development

Shard Health & Repair

# Check shard system health
flint shard check

# Fix issues in a specific shard
flint shard heal <name>
flint shard heal <name> --dry-run

# Reinstall a shard's install entries
flint shard reinstall <name>
flint shard reinstall <name> --force

Shard Repos

Shards can declare Git repositories in their shard.yaml:

repos:
  - name: my-templates
    url: https://github.com/user/my-templates.git
    branch: main

Repos are cloned to Shards/(System) Repos/<name>/ (gitignored). Use flint shard pull to sync repos.

Shard Scripts

Shards can include executable scripts in their scripts/ directory:

# List available scripts
flint shard scripts <name>

# Run a script
flint shard <name> <script-name> [args...]

# Run arbitrary command in shard directory
flint shard <name> exec <command...>

Scripts run with the flint root as working directory and receive FLINT_ROOT and FLINT_SHARD environment variables. Runner selected by extension: .js (node), .ts (tsx), .py (python3), .sh (bash).

Available Shards

Core / Flint (f)

Base shard system. Provides terminal agent conventions, navigation patterns, concept notes, and file operation guidelines. Foundation for all other shards.

Projects (proj)

Task management with status tracking. Creates (Task) documents with status (draft, todo, in-progress, review, done), priority, and completion tracking.

Increments (inc)

Version-based work tracking using X.Y.Z notation:

• X (Checkpoint): Major milestones
• Y (Stream): Feature work or themes
• Z (Iteration): Individual work sessions

Plan (plan)

High-level planning that maps to human intention. Creates (Plan) documents with status: draft -> approved -> spent.

Notepad (ntpd)

Document-based brainstorming. Creates numbered notepad files for quick capture before ideas become formal documents.

OrbCode (orbc)

Semantic mapping of codebases for agent-operated development. Creates structured documentation that maps projects, features, systems, and data structures.

Reports (rpt)

Research findings, code reviews, and concept explainers.

Learning Reports (lrpt)

Pedagogically optimized educational content generation with research-backed learning techniques.

Flintknapping (knap)

Multi-session iterative refinement workflows. Create artifacts through structured iteration with human-in-the-loop review points.

Comments (cmts)

Inline document comments using %%comment%% syntax for collaborative annotation.

Using Shards

Loading Context

Agents load shard context by reading the init file:

@Shards/Projects/init-proj.md

The init file explains the shard's concepts, conventions, and available capabilities.

Using Skills

Skills are invoked by reading the skill file:

Use the archive skill: @Shards/Projects/skills/sk-proj-archive_tasks.md

Skills contain step-by-step instructions the agent follows.

Using Templates

Templates define document structures:

Create a task using: @Shards/Projects/templates/tmp-proj-task.md

Templates include placeholders and generation instructions.

Using Workflows

Workflows are multi-step processes with human checkpoints:

Follow: @Shards/Projects/workflows/wkfl-proj-create_task.md

Reading Knowledge

Knowledge files provide deep reference on specific topics:

Read: @Shards/Projects/knowledge/knw-proj-conventions.md

Mods

Mods are environment modifications that configure external tools to work with Flint. Unlike shards (which are prompt-based), mods install files, run shell commands, and provide scripts that integrate with the broader development environment.

Shards vs Mods

Mod Configuration (mod.yaml)

version: "1.0.0"
name: "Claude Code"
shorthand: "cc"
description: "Configure Claude Code for this Flint"

install:
  - source: CLAUDE.md
    dest: CLAUDE.md
    force: true
  - source: settings.json
    dest: .claude/settings.json
    once: true

onInstall: "echo 'Claude Code configured'"
onSync: "echo 'Syncing Claude Code config'"

Install entries support template variables:

• {{flint.name}} - Flint name
• {{flint.created}} - Creation timestamp
• {{mod.name}} - Mod name
• {{mod.shorthand}} - Mod shorthand
• {{uuid}} - Random UUID
• {{date}} - Current date
• {{now}} - Current timestamp

Installing Mods

# From GitHub
flint mod install NUU-Cognition/flint-mod-claude-code

# From local path
flint mod install path:./Mods/(Dev) My Mod

# Force overwrite existing files
flint mod install NUU-Cognition/flint-mod-claude-code --force

Listing Mods

# Installed mods
flint mod list

# Source declarations from flint.toml
flint mod list --sources

Updating and Uninstalling Mods

# Update all non-dev mods
flint mod update

# Uninstall a mod
flint mod uninstall <name>

Dev Mods

Like dev shards, you can author mods locally:

# Create a new dev mod
flint mod create "My Mod" -s mm -d "My custom mod"

# Clone an existing mod for development
flint mod dev NUU-Cognition/flint-mod-claude-code

Dev mods use (Dev) folder prefix and dev = true in flint.toml.

Mod Scripts

Mods can expose executable scripts:

# List available scripts
flint mod scripts <name>

# Run a script
flint mod <name> <script-name> [args...]

Mod Lifecycle Hooks

Hooks are shell commands with a 30-second timeout.

Best Practices

Load shards on demand. Don't load every init file at session start. Load when you need that shard's capabilities.

Read init before using. The init file explains conventions. Don't guess - read the instructions.

Respect shard boundaries. Each shard manages its domain. Don't manually edit shard-managed dashboards.

Check dependencies. Some shards depend on others. The CLI handles this automatically, but understand the relationships.

Common Mistakes

• Loading all shards - Context overload. Load what you need.
• Editing managed files - Files with force: true may be overwritten on update
• Ignoring conventions - Each shard has naming and tagging conventions. Follow them.

Related

• Module - Mesh - Shards create and manage Mesh documents
• Reference - CLI Commands - Full CLI reference
• Reference - Configuration - Shard and mod configuration in flint.toml