zai-reference

name	zai-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"}

Language and Coding Standards

• Communication: Always talk in Thai when interacting with users.
• Code & Technical Assets: All code, comments, documentation, and technical definitions must be in English.

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/zai-reference/SKILL.md - MANDATORY if the file exists.

This file contains project-specific rules accumulated by /zai-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 /zai-plan, /zai-implement, /zai-explore, or /zai-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

ZeaZ Platform & apps/* Monorepo Rules

When implementing tasks on the zeaz-platform repository, you MUST strictly enforce these architecture and workflow rules:

1. Monorepo Architecture (apps/*): The platform is a unified monorepo. ALL applications, microservices, frontends, and AI toolings (e.g., zLinebot, zwallet, zdash) reside inside the apps/ directory. Do not create top-level directories for apps. When refactoring or adding features, always scope your work to the specific apps/<app-name>/ folder.
2. Environment Variables: Avoid scattering .env files. Consolidate environment variables into a central .env.example inside the respective app folder. Canonical Cloudflare variables (e.g. CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID) MUST be used instead of legacy CF_ variants.
3. Commit Workflow: NEVER use git commit or git push directly. ALWAYS stage your intended files with git add and commit using make gpg-finalize COMMIT_MSG="..." from the repository root to ensure all GitOps and DevSecOps checks pass.
4. Security: NEVER commit or generate real secrets. Unsafe placeholders like test-secret-value-value-value, test-secret-value-value-value, test-secret-value-value-value are FORBIDDEN.
5. Language: Code, documentation, and technical definitions MUST be in English.

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

<   >

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

• /zai-reference list - read and display <resolved references dir>/INDEX.md or list files in the directory
• /zai-reference show <name> - read and display the reference content (.md is optional)
• /zai-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:

• /zai-plan and /zai-implement can read them for domain context
• /zai-grounded can use them as evidence sources
• /zai-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