Reference Creator

Create structured knowledge references from external sources and store them in the configured references directory so other AI Factory skills can reuse them later.

Step 0: Load Config

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.references and paths.rules_file
• Language: language.ui for prompts

If config.yaml doesn't exist, use defaults:

• references/: .ai-factory/references/
• RULES.md: .ai-factory/RULES.md
• Language: en (English)

Project Context

Read .ai-factory/skill-context/aif-reference/SKILL.md - MANDATORY if the file exists.

This file contains project-specific rules accumulated by $aif-evolve from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

• Treat them as project-level overrides for this skill's general instructions
• When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins
• When there is no conflict, apply both
• CRITICAL: skill-context rules apply to ALL outputs of this skill - including the generated reference files. If a skill-context rule says "references MUST include X" - you MUST comply.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated - fix the output before presenting it to the user.

When To Use

• AI needs documentation it was not trained on or may know only partially
• You want grounded answers based on specific docs, specs, or internal files
• You want reusable domain context for $aif-plan, $aif-implement, $aif-explore, or $aif-grounded
• You want a durable knowledge artifact instead of one-off conversation context

Argument Detection

Check $ARGUMENTS:
- Contains "--update"        -> Update Mode: refresh existing reference
- Contains URLs (http/https) -> URL Mode: fetch and process web sources
- Contains file paths        -> File Mode: process local documents
- "list"                     -> List existing references
- "show <name>"              -> Show reference content
- "delete <name>"            -> Delete a reference (with confirmation)
- Empty                      -> Interactive mode

Workflow

Step 0.1: Setup

Ensure the resolved references directory exists:

mkdir -p <resolved references dir>

Check for existing references to avoid duplicates:

ls <resolved references dir>

If --name <ref-name> is provided, use it as the reference name. If --update is provided, find and update the existing reference instead of creating a new one.

Step 1: Collect Sources

For URLs:

For each URL:

1. Fetch the page using WebFetch and extract:
   • main topic and purpose
   • key concepts, terms, and definitions
   • code examples and patterns
   • API methods, parameters, return types, and signatures
   • configuration options with defaults
   • best practices and recommendations
   • error handling and edge cases
   • version information and compatibility notes
   • links to critical sub-pages
2. If critical sub-pages are referenced, fetch them too (up to 8 extra pages per source URL).
3. If obvious gaps remain, run 1-2 targeted WebSearch queries to fill them.

For local files:

1. Read each file with Read
2. If the file references other local files, read those too (up to 5 levels of includes)
3. Detect the format (markdown, HTML, JSON, YAML, plain text) and extract accordingly

For interactive mode:

Ask the user:

1. What topic or technology should this reference cover?
2. Do they have URLs or local files, or should you search?
3. What aspects matter most for their use case?

Step 2: Synthesize the Reference

Transform collected material into a structured reference document.

Reference file format:

# <Topic> Reference

> Source: <list of source URLs or file paths>
> Created: YYYY-MM-DD
> Updated: YYYY-MM-DD

## Overview

<1-3 paragraph summary>

## Core Concepts

<Concept 1>: <clear explanation>
<Concept 2>: <clear explanation>

## API / Interface

<Only if applicable. Preserve exact signatures and types from source docs.>

## Usage Patterns

<Practical code examples organized by use case.>

## Configuration

<Options, defaults, valid values. Table format preferred.>

## Best Practices

<Numbered list with reasoning>

## Common Pitfalls

<What goes wrong and how to avoid it>

## Version Notes

<Only if relevant. Breaking changes, migration notes, deprecations.>

Quality rules:

• No hallucination - include only what was actually found
• Preserve code verbatim - docs examples must stay exact
• Actionable over academic - optimize for useful lookup
• Dense - maximize useful information per line
• Complete signatures - APIs need full parameters, types, and returns
• Source attribution - always include source URLs or paths

Step 3: Name and Save

Naming convention:

• Derive from topic: react-hooks.md, fastapi-endpoints.md, docker-compose.md
• Use lowercase, hyphens, .md
• If --name was provided, use that (add .md if missing)
• Avoid generic names like reference.md

Save to: <resolved references dir>/<name>.md

Step 4: Register in Index

Check if <resolved references dir>/INDEX.md exists. Create or update it:

# References Index

Available knowledge references for AI agents.

| Reference | Topic | Sources | Updated |
|-----------|-------|---------|---------|
| [react-hooks](react-hooks.md) | React Hooks API and patterns | react.dev | 2026-03-20 |
| [docker-compose](docker-compose.md) | Docker Compose configuration | docs.docker.com | 2026-03-20 |

Step 5: Report

Show the user:

• reference name and path
• size (line count)
• sections included
• source URLs or file paths used
• how to use it in later AI Factory workflows

Update Mode (--update)

When --update is present:

1. Find the existing reference by --name or matching sources
2. Re-fetch the sources listed in the header
3. Compare new material with existing content and update only changed sections
4. Preserve Created:, update Updated:
5. Report what changed

List / Show / Delete

• $aif-reference list - read and display <resolved references dir>/INDEX.md or list files in the directory
• $aif-reference show <name> - read and display the reference content (.md is optional)
• $aif-reference delete <name> - ask for confirmation, delete the file, and update INDEX.md

Integration With Other Skills

References in the resolved references directory are available to all AI Factory skills:

• $aif-plan and $aif-implement can read them for domain context
• $aif-grounded can use them as evidence sources
• $aif-explore can reference them during research

To make a skill aware of a specific reference, mention it in the resolved RULES.md file:

## References
- For <topic> details, see `<resolved references dir>/<name>.md`

Artifact Ownership

• Primary ownership: the resolved references directory (default: .ai-factory/references/)
• Shared ownership: the resolved references index file (INDEX.md inside that directory)
• Read-only: all other .ai-factory/ files
• Config policy: config-aware. Use paths.references for storage and paths.rules_file when pointing other skills at a saved reference.

Guardrails

• Max reference size: aim for under 1000 lines per reference. If larger, split into multiple files and create a directory inside the resolved references dir with an INDEX.md inside
• No duplication: check existing references before creating a new one
• No stale data: always include sources so the reference can be refreshed
• No opinions: references should reflect sources, not personal preferences
• Respect access: if a URL requires authentication or fails to load, report that instead of guessing