| name | f0-ai-config-hygiene |
| description | Audits AI configuration files (AGENTS.md, copilot-instructions.md, SKILL.md files) for instruction duplication. Load when modifying any AI config file, adding a new skill, or reviewing whether instructions have drifted out of sync. |
F0 AI Config Hygiene
Audit skill that detects instruction duplication across AI configuration files in the F0 monorepo.
This skill is audit-only — it reports findings and recommends fixes, but does not auto-modify files.
All changes require human judgment.
When to Use
Load this skill when:
- Adding a new rule to any
AGENTS.md
- Creating or modifying a
vendor/skills/*/SKILL.md
- Modifying
.github/copilot-instructions.md
- Reviewing a PR that touches AI config files
- Suspecting that two files have drifted out of sync
When NOT to Use
- When making changes to component code, tests, or stories — load a component skill instead
- When writing a brand-new skill from scratch where no duplication is possible yet
Ownership Model
This is the authoritative table of what each file owns. A rule belongs in exactly one file.
Other files that reference the same topic must link to the owner, not restate the content.
| Layer | File | Owns |
|---|
| 1 | AGENTS.md (root) | Monorepo structure, key principles (TypeScript strict, pnpm, English), factorial-skills bootstrap |
| 1 | .github/copilot-instructions.md | Thin Copilot Chat / completion entry point only. Everything else defers to root AGENTS.md. |
| 2 | packages/react/AGENTS.md | All F0 React component conventions: naming, folder structure, props, context, TypeScript, testing, styling, i18n, a11y, commands |
| 2 | packages/react/docs/definition-of-done.mdx | The lifecycle contract: phases, exit criteria, maturity levels, promotion gates |
| 2 | packages/react/docs/components-maturity.mdx | What each maturity level (experimental, stable, deprecated) means; clarification that internal is not a level |
| 2 | packages/react/docs/design-review.mdx | The 10-category design review checklist used in Phase 2 |
| 2 | packages/react/docs/contributions.mdx | Human entry-point for "I want to…" — links to all the contracts above |
| 2 | packages/react/docs/development/release-and-versioning.mdx | Versioning, alpha/release flow, and the Deprecation & Removal policy |
| 3 | vendor/skills/*/SKILL.md | On-demand workflow orchestration and key-rules summary for a specific task. References AGENTS.md, never restates its rules. |
| 3 | vendor/skills/*/references/*.md | Detailed code examples, patterns, and templates that expand on AGENTS.md rules with implementation detail |
| 3 | vendor/skills/a11y/SKILL.md | External community skills (tracked in /skills-lock.json). Treat as read-only; don't add F0-specific rules to them. |
Audit Workflow
Step 1 — Inventory all AI config files
Collect the full list of files to audit:
/AGENTS.md
/.github/copilot-instructions.md
/packages/react/AGENTS.md
/vendor/skills/*/SKILL.md
/vendor/skills/*/references/*.md
Read each file in full. Build a mental map of what topics each file covers.
Step 2 — Extract rules from AGENTS.md files
From packages/react/AGENTS.md, list every distinct rule (one rule per line). Group by section:
- Component Architecture
- Props
- Context and State
- TypeScript
- Testing
- Styling
- i18n
- Accessibility
- Code Quality
Step 3 — Check each skill for rule restatements
For each SKILL.md and references/*.md, check whether it:
- Restates a rule from AGENTS.md verbatim or near-verbatim → Flag as duplication
- Expands a rule with a code example or implementation detail → Acceptable (this is the skill's job)
- Cross-references AGENTS.md with language like "see
packages/react/AGENTS.md" → Correct pattern
Step 4 — Check copilot-instructions.md vs. root AGENTS.md
copilot-instructions.md should contain only:
- A one-line project description
- A pointer to
packages/react/AGENTS.md
- Any context unique to Copilot Chat (e.g. workspace-specific behavior)
Flag any content in copilot-instructions.md that is also present in AGENTS.md (root).
Step 5 — Check root AGENTS.md vs. packages/react/AGENTS.md
Root AGENTS.md should contain only monorepo-wide concerns. Flag any React-specific rules
(naming, props, styling, testing, i18n, a11y) that have leaked into the root file.
Step 6 — Report findings
Report using this format:
## AI Config Hygiene Report
### BLOCKING — Duplication (must fix before merging)
- [FILE A, line N] Rule: "<exact rule text>"
Duplicates: [FILE B, line N] — owner is FILE B
Fix: Replace in FILE A with: "See `packages/react/AGENTS.md` — <section name>"
### SUGGESTION — Potential drift risk
- [FILE A, line N] "<text>" partially overlaps with [FILE B, line N]
Recommendation: Clarify whether FILE A is expanding (acceptable) or restating (remove)
### PASS — No duplication found
- [list of files checked that are clean]
Severity Classification
| Severity | Condition |
|---|
| BLOCKING | A rule is stated verbatim or near-verbatim in two or more files with no cross-reference |
| BLOCKING | A skill's SKILL.md contains AGENTS.md rules without attributing them to AGENTS.md |
| BLOCKING | copilot-instructions.md contains content that is not unique to Copilot Chat/completions |
| SUGGESTION | A skill restates a rule but does cross-reference AGENTS.md (low drift risk, but still noisy) |
| SUGGESTION | A reference file repeats a rule summary already in the parent SKILL.md |
| PASS | A skill expands an AGENTS.md rule with code examples without restating the rule itself |
Common Duplication Patterns to Watch
These are the specific patterns found historically in this codebase:
Pattern A — Skill "Key Rules" that mirror AGENTS.md
Skills sometimes have a "Key Rules" section that lists AGENTS.md rules for quick reference. This
creates a maintenance liability. The fix is either:
- Remove the rules and replace with:
"Always check \packages/react/AGENTS.md` — it has the concise rules."`
- Or keep only rules that are not already in AGENTS.md (rules specific to the skill's workflow)
Pattern B — Test file naming stated in multiple places
"Test files: .test.tsx / .test.ts — never .spec.ts" and "No snapshot tests" appear in both
packages/react/AGENTS.md and f0-unit-testing/SKILL.md. The skill should reference AGENTS.md
instead of restating these.
Pattern C — copilot-instructions.md cloning AGENTS.md
copilot-instructions.md has historically contained the full monorepo structure and key principles
from root AGENTS.md. Since GitHub Copilot coding agent reads AGENTS.md natively, and
copilot-instructions.md serves a different Copilot feature (Chat/completions), keep
copilot-instructions.md minimal — just enough for inline completions to be useful.
Pattern D — Quality gate skip conditions stated twice
The three skip conditions (user asks to skip, docs-only change, auto-generated files) appear
in both packages/react/AGENTS.md and f0-quality-gate/SKILL.md. The canonical list lives in
AGENTS.md; the skill should reference it rather than duplicate it.
Pattern E — Lifecycle rules drifting from the contract
The definition-of-done.mdx is the contract for the F0 component lifecycle (phases, exit criteria,
maturity levels). Skills like f0-component-contribution, f0-component-promotion, and
f0-experimental-component-migration are operational playbooks that execute the contract.
When a phase exit criterion (e.g., "≥3 product teams adopted") is restated in a skill, the skill
becomes a maintenance liability — if the contract changes, every skill must be updated. The fix:
have the skill reference the contract section (e.g., "see definition-of-done.mdx Phase 4")
rather than restating the criterion.
Fix Guidance
When a duplication is found, the preferred fix depends on context:
| Situation | Preferred fix |
|---|
| Skill restates an AGENTS.md rule with no additions | Delete from skill; add "See \packages/react/AGENTS.md`"` reference |
| Skill restates a rule AND adds a code example | Keep the example; replace the rule restatement with a cross-reference sentence |
copilot-instructions.md has content that's also in root AGENTS.md | Remove from copilot-instructions.md; it will be read from AGENTS.md by the coding agent anyway |
| Two skills both state the same rule | Identify the canonical skill; have the other reference it |
Root AGENTS.md has React-specific rules | Move to packages/react/AGENTS.md; root AGENTS.md links down |
PR Checklist for AI Config Changes
Before merging any PR that touches AI config files, verify:
