Skill Preflight

Creation Guard: Pre-Flight Duplicate Check

Prevent duplicate functionality by analysing existing skills and agents 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)

Trigger phrases:

• "Create a skill for..."
• "I want a new skill that..."
• "Let's add an agent for..."
• Any intent to create new automation/tooling

Process

Step 1: Identify the Proposal

Extract from the request:

• Name: Proposed name (kebab-case)
• Type: skill | agent
• 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:

1. Read [skills/shared/skill-index.md](../shared/skill-index.md) — scan the categorised table for potential duplicates by name and purpose
2. Keyword search — grep skills and agents for each keyword:

Grep for each keyword across:
  - skills/*/SKILL.md (frontmatter + body)
  - .claude/agents/*.md (frontmatter + body)

1. Agent scan — read frontmatter of each agent to check purpose overlap:

Glob: .claude/agents/*.md
Read first 20 lines of each match

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:

1. Does something similar already exist?
2. Could this be added to an existing artifact?
3. Would a user know to look for this vs the existing one?
4. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: flonat
• Source: flonat/claude-research
• License: MIT

Install and usage instructions live in the source repository linked above.