Riglet Creator

Creating effective riglets means writing knowledge (SKILL.md) that agents will rely on. This guide focuses on how to write high-quality documentation for riglets, organized efficiently.

For the structural/technical side of riglets (what goes in the Nix module, metadata fields, schema), see the riglet agent-rig-system's SKILL.md and references/metadata-guide.md.

Core Principles

Define the Main Intent

Ask yourself: what is the end goal here? What should this riglet teach? The intent metadata is there to help you here. It should guide how you approach the writing of a riglet. As a reminder, the possible intents are:

• base: "abstract" riglet (e.g. to define options) solely meant to be imported by others to factorize configuration. Cannot be disclosed in a manifest
• sourcebook: compendium of knowledge, glossary, useful domain knowledge
• toolbox: open-ended set of tools related together
• cookbook: operational know-how, heuristics, tricks and techniques that are useful to apprehend an otherwise complex toolset or domain
• playbook: specific procedure or workflow to follow in a rigorous manner

A riglet should fall under one of these categories. If several apply, then it might be a better idea to split it into several. Discuss that with your user. Several riglets, each one with a clear focus, are better than one unorganized riglet that tries to cover everything without a real goal. Remember riglets can depend on each other via imports, so for example a very specialized "playbook" can depend on tools explained and documented in a more general "toolbox".

Concise is Key

Agents share context windows with conversation history, system instructions, and other riglets in the rig. Context is a shared resource.

Default assumption: Agents are already very capable. Only include knowledge agents don't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"

Prefer concrete examples over verbose explanations. Prefer links to references over embedding everything in SKILL.md.

Set Appropriate Degrees of Freedom

Match documentation specificity to the task's fragility and variability:

High freedom (general guidance): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the process. Example: "Organizing commits in JJ" — many strategies work.

Medium freedom (documented patterns with options): Use when a preferred pattern exists but some variation is acceptable. Example: "Creating PDFs with Typst" — follow the basic template but customize styling.

Low freedom (specific procedures, few choices): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed. Example: "Setting up encrypted credentials" — must follow exact steps.

Think of it as a path: a narrow bridge with cliffs needs specific guardrails (low freedom, detailed steps), while an open field allows many routes (high freedom, general principles).

Structure: Know What Goes Where

Riglets have different components for different purposes:

SKILL.md - Primary workflows and procedures

• What: Core knowledge agents load first
• When: Procedures, common workflows, decision trees
• Length: ~100-150 lines ideally
• Load cost: Loaded for every interaction

references/ - Deep knowledge, advanced topics

• What: Advanced patterns, troubleshooting, detailed specifications
• When: Complex scenarios, edge cases, detailed reference material
• Length: 50-200 lines each, with TOC if >100
• Load cost: Only loaded when agent determines it's needed

tools in Nix - Executable packages

• What: CLI tools, compilers, interpreters needed by the riglet
• When: When the riglet teaches workflows that use specific tools
• Load cost: Built into rig environment, always available

Keep information in one place: SKILL.md or references, not both. Prefer references for detailed material unless it's core to the riglet—this keeps SKILL.md lean and makes information discoverable without hogging context.

Understanding the Riglet with Concrete Examples

Skip this step only when the riglet's patterns are already clearly understood.

Before writing a riglet, deeply understand what it will teach. Concrete examples drive effective documentation.

To create an effective riglet, clarify the scope with concrete examples:

• "What workflows does this riglet enable?"
• "What are realistic use cases?"
• "What problems does it solve?"
• "What would agents ask for that this riglet answers?"

For example, when building a riglet about version control with JJ:

• What functionality should it cover? (Creating changes, managing history, collaboration?)
• Can you give concrete examples? ("I need to reorganize my commits" or "I'm collaborating with git users")
• What would an agent say that should trigger this riglet?

To avoid overwhelming agents later, ask progressively—start with the most important questions. Conclude when the riglet's scope is clear and you have concrete examples.

Planning the Reusable Documentation Contents

Transform concrete examples into effective documentation by analyzing what knowledge is needed.

For each concrete example/workflow:

1. What knowledge is needed to execute it? (procedures, patterns, concepts)
2. What details are essential vs. advanced? (core flow vs. edge cases)
3. What reference materials would help? (checklists, templates, troubleshooting)

Example: For a JJ riglet handling "reorganizing commits":

1. Agents need to understand: revsets, rebasing, interactive rebase workflows
2. Essential: Basic rebase commands; Advanced: complex revset patterns
3. Reference materials: Revset syntax guide, troubleshooting merge conflicts

Example: For a PDF riglet handling "extracting tables from PDFs":

1. Agents need: Understanding of PDF structure, table detection, format conversion
2. Essential: Simple table extraction; Advanced: handling complex nested tables
3. Reference materials: Format specifications, edge cases, tool limitations

Example: For a Typst riglet handling "generating documents":

1. Agents need: Typst syntax, layout patterns, styling fundamentals
2. Essential: Basic template structure; Advanced: custom layouts and functions
3. Tools needed: typst compiler, pandoc for format conversion
4. Configuration: Templates for common document types
5. Reference materials: Syntax reference, styling guide, troubleshooting layout issues

From this analysis, create a list of:

• Main sections for SKILL.md (primary workflows)
• Reference files needed (advanced patterns, troubleshooting, checklists)
• Tools to include (what agents will need to execute workflows)
• Configuration (templates, pre-configured settings)

Writing Effective SKILL.md

SKILL.md is the core knowledge. Write for agent efficiency:

Content Organization

Start with overview:

# My Riglet

This riglet teaches [what it covers].

Primary use cases:
- Use case 1
- Use case 2
- Use case 3

See references/advanced.md for deeper patterns.

Remain concise in this section, DO NOT duplicate info that is already in the meta.description and meta.whenToUse.

For documentation patterns, see patterns.md.

Documentation Patterns

For proven patterns to organize riglet documentation, see patterns.md. It covers:

• Sequential workflows
• Domain-specific organization
• Conditional details with progressive disclosure
• Troubleshooting-driven structures
• Converting Skills to riglets

Writing Guidelines

Avoid deeply nested references - Keep reference links one level deep. All reference files should link directly from SKILL.md, not from other references.

Use imperative/infinitive form:

• Good: "Use jj to manage changes"
• Avoid: "This riglet manages changes" or "JJ is a version control system"

**Avo