home / skills / pproenca / dot-skills / missing-references

missing-references skill

safe

This skill validates reference consistency by identifying missing reference files for rules listed in Quick Reference and reports gaps.

This is most likely a fork of the missing-references skill from pluk-inc

npx playbooks add skill pproenca/dot-skills --skill missing-references

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

547 B

---
name: missing-references
description: This skill references rules that do not have corresponding files in the references directory.
---

# Missing References Skill

This skill has rules in Quick Reference that are missing reference files.

## Quick Reference

### 1. Example Category (CRITICAL)

- `missing-rule-one` - This rule has no reference file
- `missing-rule-two` - This rule also has no reference file
- `existing-rule` - This rule has a reference file

## How to Use

This skill is used for testing reference consistency validation.

Overview

This skill checks for rules listed in a Quick Reference that do not have corresponding reference files in the references directory. It highlights mismatches so you can keep rule documentation and reference files synchronized. Use it to surface missing reference files and avoid broken links or incomplete rule sets.

How this skill works

The skill parses the Quick Reference section to extract rule identifiers and then scans the references directory for files that match those identifiers. It reports any identifiers present in the Quick Reference that lack a corresponding file, and marks rules that are covered by existing reference files. The output is a concise list of missing and existing references for easy remediation.

When to use it

When validating a new or updated Quick Reference list before release
During CI checks to prevent broken or incomplete rule documentation
When onboarding new rules to ensure each rule has an associated reference file
Before publishing or packaging skills to external consumers
When auditing documentation consistency across a skills collection

Best practices

Keep rule IDs consistent between Quick Reference entries and reference filenames
Run this check as part of your continuous integration pipeline
Require a passing report (no missing references) before merging rule changes
Name reference files using the exact rule identifiers to avoid false positives
Automatically generate placeholder reference files for new rules to prompt authoring

Example use cases

A maintainer adds new rules to Quick Reference and runs the skill to find missing files
A CI job runs the skill to block merges when Quick Reference and references diverge
An audit identifies outdated Quick Reference entries that reference removed or renamed files
A documentation workflow that scaffolds missing reference files so authors can fill details
A pre-release validation step to ensure published skill packages include all referenced files

FAQ

Does the skill modify files or create missing references automatically?

No. The skill reports missing references but does not create or modify files. Use its output to decide whether to add or scaffold reference files.

What counts as a match between a Quick Reference rule and a reference file?

A match requires the rule identifier in the Quick Reference to correspond exactly to a reference filename or a clearly defined mapping convention in your project.