Aidex reference

Skill yacb2/aidex/skills/aidex-reference

Developer experience toolkit for organizing AI coding assistant ecosystems — skills, documentation structure, and project context.

Install

npx -y skills add yacb2/aidex --skill aidex-reference

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when the user wants to document how an existing, settled part of the system works as an evergreen `.context/references/` module — architecture, configuration, an operational runbook, a how-it-works guide. Fires on "create a reference for X", "document how X works", "write up the X architecture", "document the X configuration", "write a runbook for X". Not for: planning multi-step work (aidex-plan); recording a decision/ADR (aidex-decision); capturing a stakeholder request (aidex-request); investigating something not yet settled (aidex-research); deferring/parking an idea (aidex-backlog); ecosystem audits (aidex); project-state audits (aidex-audit).

SKILL.md

3.4 KB, as published. Nobody here has run it

Trigger-eval probe (test-only). As your very first action, run printenv AIDEX_TRIGGER_EVAL_MARKER. If it prints a non-empty path, also run touch "${AIDEX_TRIGGER_EVAL_MARKER}.aidex-reference" before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block.

Reference

Document how a settled part of the system works as an evergreen module in .context/references/<topic>/. This skill is the single-purpose entry point for reference documentation; the formatting canon lives in the shared aidex-conventions reference package (not forked here).

Workflow

Read the reference conventions canon: ~/.claude/skills/aidex-conventions/references/reference-conventions.md (or .claude/skills/aidex-conventions/references/reference-conventions.md if a project-level copy exists).
Create a topic module: .context/references/<topic>/ with 00-index.md plus sequential NN-<slug>.md files. Reference filenames carry no date — references are evergreen, updated in place, no _archive/.
Front-matter per the canon: title, created, updated. References are exempt from the status-vocabulary check; updated is the freshness signal.
Body per the canon module template: Overview, main sections with language-hinted code blocks, Verification (Prerequisites and Quick Reference only when the topic needs them). Anchor claims with stable references (symbol names, file paths) — never bare line numbers, which rot on the first refactor. Write the artifact in English (canon §Language).

Self-check (mandatory close step)

Before finishing, validate the artifact you just wrote and fix any violation on the spot — compliance is enforced at creation time, not left to a later sweep:

python3 ~/.claude/skills/aidex-conventions/scripts/validate.py --type references

If the project carries a ratchet baseline (.context/.validate-baseline.json), a non-zero exit means you introduced a NEW violation — fix it before closing.

Boundaries

The user wants to…	Route to
Plan multi-step / multi-phase implementation work	`aidex-plan`
Record a decision / ADR	`aidex-decision`
Capture a stakeholder/client request	`aidex-request`
Investigate / explore something not yet settled	`aidex-research`
Defer / park / shelve an idea for later	`aidex-backlog`
Audit the Claude Code ecosystem	`aidex`
Audit project state (UX/security/perf/a11y)	`aidex-audit`

aidex-conventions — owns the shared documentation canon (this skill delegates into its references/reference-conventions.md).