aif-reference

name	aif-reference
description	Create knowledge references from URLs, documents, or files for use by AI agents. Fetch, process, and store structured references in the configured references directory (default: .ai-factory/references/).
argument-hint	<url|path> [url2|path2] [--name <ref-name>] [--update]
allowed-tools	Read Write Edit Glob Grep Bash(mkdir *) Bash(ls *) Bash(wc *) WebFetch WebSearch AskUserQuestion
disable-model-invocation	false
metadata	{"author":"ai-factory","version":"1.0","category":"knowledge-management"}

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 and summaries, language.artifacts for generated reference artifacts, and language.technical_terms for human-readable technical terminology in references

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

• references/: .ai-factory/references/
• RULES.md: .ai-factory/RULES.md
• ui_language: en
• artifact_language: en
• technical_terms_policy: keep

Resolved language values:

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"

If technical_terms_policy is not one of keep, translate, or mixed, treat it as keep. Legacy values such as english also behave like keep.

All AskUserQuestion prompts, progress updates, summaries, and next-step guidance MUST be written in ui_language.

Generated reference files and the reference INDEX.md MUST be written in artifact_language.

Templates and examples define structure, not fixed English output. If artifact_language is not en, translate human-readable headings, labels, summaries, concept explanations, best-practice prose, pitfalls, and index descriptions before saving. Preserve source quotations, source titles, URLs, local paths, code examples, API signatures, command names, config keys, package names, version strings, raw errors, and link targets unchanged. Apply technical_terms_policy to other human-readable terminology.

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:

Render this structure in artifact_language before saving. The headings below are canonical structure labels, not fixed English output.

# <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:

Write human-readable index headings, topic descriptions, and source summaries in artifact_language; keep filenames, links, URLs, and dates unchanged.

# 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, paths.rules_file when pointing other skills at a saved reference, language.ui for prompts and summaries, language.artifacts for generated reference artifacts, and language.technical_terms for human-readable terminology policy.

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