| name | skill-preflight |
| description | Deliver a pre-flight duplicate check before creating new skills or agents. Use when the user requests a pre-flight duplicate check before creating new skills or agents. |
| allowed-tools | ["Read","Glob","Grep","AskUserQuestion"] |
Creation Guard: Pre-Flight Duplicate Check
Prevent duplicate functionality by analysing existing skills, agents, and rules before creating new ones. Intercepts creation intent, searches for overlap, and recommends one of 5 actions.
When to Use
Invoke before creating ANY new:
- Skill (
skills/*/SKILL.md)
- Agent (
.claude/agents/*.md)
- Rule (
rules/*.md)
Trigger phrases:
- "Create a skill for..."
- "I want a new skill that..."
- "Let's add an agent for..."
- "We need a rule for..." / "add a rule that..."
- Any intent to create new automation/tooling
Rules need this most, not least. A duplicate skill is visible — it shows up
in the catalogue and the slash menu. A duplicate rule is invisible: both copies
load silently as system instructions, and the first sign of trouble is two
subtly different versions of the same policy competing. Rules are also
break-the-glass infrastructure, so an unnecessary one is a standing cost on
every session. Check for an existing rule to amend before writing a new one
— amendment is the usual correct outcome for rules, where PROCEED is the usual
outcome for skills.
Process
Step 1: Identify the Proposal
Extract from the request:
- Name: Proposed name (kebab-case)
- Type: skill | agent | rule
- Purpose: What it does (one sentence)
- Key Functions: 3-5 main capabilities
- Keywords: Searchable terms related to functionality
Step 2: Search Existing Artifacts
Run these searches in parallel:
- Read
skills/shared/skill-index.md — scan the categorised table for potential duplicates by name and purpose
- Keyword search — grep skills, agents, and rules for each keyword:
Grep for each keyword across:
- skills/*/SKILL.md (frontmatter + body)
- .claude/agents/*.md (frontmatter + body)
- rules/*.md (frontmatter + body)
- Agent scan — read frontmatter of each agent to check purpose overlap:
Glob: .claude/agents/*.md
Read first 20 lines of each match
- Rule scan — list every rule and read its Principle:
Glob: rules/*.md
Read the frontmatter + "## Principle" section of each candidate
A rule's filename often understates its reach: the policy you want may live
inside a broader rule under a different name. Check docs/components/rules.md
for the full table, and read the Principle rather than matching on the title —
bibliography-routing.md owns paper-lookup routing, which its name does not
advertise. Also check the paths: frontmatter: a rule that exists but is
path-scoped away from where you need it is a scoping fix, not a new rule.
Step 3: Analyse Overlap
For each potentially related artifact, assess:
| Criterion | Question |
|---|
| Functional overlap | Does it do the same thing? (0-100%) |
| Naming confusion | Could names be confused? |
| Extension potential | Could the proposal extend this instead? |
| Composition | Could existing artifacts compose to achieve this? |
Step 4: Generate Recommendation
Based on analysis, recommend ONE of:
| Recommendation | Criteria | Action |
|---|
| PROCEED | <20% overlap, genuinely new capability | Create new artifact |
| EXTEND | 50%+ overlap with single existing artifact | Modify existing instead |
| COMPOSE | Multiple artifacts cover 80%+ combined | Create thin wrapper or document workflow |
| ITERATE | 20-50% overlap, proposal needs refinement | Refine proposal to differentiate |
| BLOCK | Would create problematic duplication | Do not create |
Step 5: Present and Confirm
Display the analysis and wait for explicit user approval before proceeding.
Output Format
════════════════════════════════════════════════════════════════
CREATION GUARD ANALYSIS
════════════════════════════════════════════════════════════════
PROPOSAL:
Type: [skill|agent]
Name: [proposed-name]
Purpose: [one sentence]
EXISTING ARTIFACTS ANALYSED: [count]
RELATED ARTIFACTS FOUND:
1. [artifact-name] ([type])
Purpose: [what it does]
Overlap: [X]% - [explanation]
2. [artifact-name] ([type])
Purpose: [what it does]
Overlap: [X]% - [explanation]
RECOMMENDATION: [PROCEED|EXTEND|COMPOSE|ITERATE|BLOCK]
RATIONALE:
[2-3 sentences explaining the recommendation]
SUGGESTED ACTION:
[Specific next step based on recommendation]
════════════════════════════════════════════════════════════════
Recommendation Details
PROCEED
- Artifact is genuinely new
- No significant overlap found
- Clear differentiation from existing tools
- Go ahead and create
EXTEND
Present extension proposal:
Instead of creating [new-name], extend [existing-name]:
Current capabilities:
- [existing feature 1]
- [existing feature 2]
Proposed additions:
- [new feature 1]
- [new feature 2]
COMPOSE
Present composition approach:
The proposed functionality can be achieved by combining:
1. [artifact-1] — handles [aspect]
2. [artifact-2] — handles [aspect]
Options:
A) Document this workflow (no new code)
B) Create thin orchestration skill
C) Add to existing skill's integration section
ITERATE
Present refinement questions:
Overlap detected with [existing-artifact].
Differentiation needed:
1. [question about scope]
2. [question about use case]
3. [question about implementation]
Please clarify to proceed.
BLOCK
Explain why creation should not proceed:
BLOCKED: Would create problematic duplication.
Existing artifact: [name]
- Already does: [capabilities]
- Your request: [same capabilities]
Alternatives:
1. Use existing: /[skill-name]
2. If missing features, extend the existing artifact
3. If different use case, explain how this differs
Post-Match Action Table
When overlap IS found, use this table to decide the specific action:
| Situation | Action |
|---|
| Nothing related found | Create new artifact |
| Same trigger + same fix as existing | Update existing (bump version, improve docs) |
| Same trigger, different root cause | Create new + add cross-links in both |
| Partial overlap (same domain, different trigger) | Add variant subsection to existing |
| Same domain, different problem | Create new + add "See also" references |
| Existing is stale or wrong | Mark deprecated + create replacement |
This complements the PROCEED/EXTEND/COMPOSE/ITERATE/BLOCK recommendation above. The recommendation decides whether to create; this table decides how to handle the relationship with existing artifacts.
Self-Check Questions
Before creating ANY new artifact, ask:
- Does something similar already exist?
- Could this be added to an existing artifact?
- Would a user know to look for this vs the existing one?
- Am I creating this because it's needed or because it's easier than finding what exists?
Naming Convention Enforcement
When creating a new skill, always name the definition file SKILL.md (uppercase). Never skill.md, Skill.md, or any other casing.
- The MCP server's skill discovery scans for
SKILL.md explicitly
- Documentation generators and
system-audit use find -name 'SKILL.md'
- On case-insensitive filesystems (macOS APFS), lowercase files appear to work locally but fail in case-sensitive contexts (Linux CI, Docker, MCP server pattern matching)
Check before writing: If the target directory already contains a skill.md (lowercase), rename it to SKILL.md first.
Anti-Patterns
| Anti-Pattern | Problem | Instead |
|---|
| Skip the check | "It's obviously new" — famous last words | Always run the analysis |
| Name-only matching | Names differ but functions overlap | Search by purpose and keywords |
| Create then merge | Merge debt accumulates fast | Check first, create once |
| Over-splitting | Two skills that always run together | Consider a single skill with phases |
Lowercase skill.md | Invisible to MCP server, audit tools, and case-sensitive systems | Always use SKILL.md (uppercase) |
Integration
This skill is invoked by skill-extract in Phase 2 to replace the old subset/partial/no-overlap check. When called from skill-extract, return the recommendation label (PROCEED/EXTEND/COMPOSE/ITERATE/BLOCK) so skill-extract can branch accordingly.
