aif-reference

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/).

Quality

68%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/aif-reference/SKILL.md

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is a well-structured, actionable workflow with clear sequencing and concrete templates. Its main weaknesses are a missing link to the bundled EXAMPLES.md and minor verbosity in the language-policy section.

Suggestions

Reference the existing bundle from the body, e.g. add a "See [EXAMPLES.md](references/EXAMPLES.md) for sample inputs and expected output" line near the Workflow section.

Collapse the duplicated defaults vs. resolved-values config list into a single table to remove redundancy in Step 0.

Add an explicit output-validation checkpoint (e.g. verify the saved reference against the quality rules before reporting) to strengthen the feedback loop.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean operational guidance (config resolution, workflow steps, templates) with only minor redundancy — the defaults vs. resolved-values restatement and the long translation-preservation list could be tightened slightly.	4 / 5
Actionability	Provides concrete commands (mkdir -p, ls), explicit WebFetch/Read usage, a full reference-file template, naming convention, and an INDEX.md schema — mostly executable with minor gaps in the synthesis step which is guidance rather than code.	4 / 5
Workflow Clarity	A clearly sequenced Step 0 → 0.1 → 1 → 5 pipeline with a duplicate-check checkpoint and confirmation guardrail on delete; the only gap is an explicit validate-the-output feedback loop, but operations are non-destructive so the cap does not apply.	4 / 5
Progressive Disclosure	Sections are well-organized, but the provided bundle file references/EXAMPLES.md is never linked or signaled from the body, leaving a real navigation gap against the actual bundle structure.	3 / 5
	Total	15 / 20 Passed

Description

66%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, third-person, and reasonably distinctive, but it omits any explicit "when to use" trigger guidance, which caps its completeness. Adding a Use-when clause would lift it from good to strong.

Suggestions

Append a trigger clause such as "Use when an AI agent needs grounded documentation it wasn't trained on, or when building reusable domain context for /aif-plan, /aif-implement, or /aif-grounded."

Add common synonym terms (e.g. "docs", "specifications", "internal files") to broaden natural keyword coverage.

Mention the supported source types as trigger phrases (e.g. "when the user pastes URLs or points to local files") to sharpen when-to-use signaling.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions — "Create knowledge references", "Fetch, process, and store structured references" — across URL, document, and file sources, with only minor coverage gaps.	4 / 5
Completeness	Has a clear "what" but no "Use when..." trigger clause; per the rubric a missing explicit trigger guidance caps completeness at 3.	3 / 5
Trigger Term Quality	Includes natural user terms ("references", "URLs", "documents", "files", "AI agents") with good coverage, though a few common synonyms (e.g. "docs") are missing.	4 / 5
Distinctiveness Conflict Risk	The "configured references directory" and "for use by AI agents" framing carve a reasonably distinct niche with only minor overlap risk against general document skills.	4 / 5
	Total	15 / 20 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 2 missing	Warning

	Total	13 / 16 Passed

Repository: lee-to/ai-factory
Path: skills/aif-reference/SKILL.md
Commit: ac92beb

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.