| name | asset-discovery |
| description | Discovers existing skills and agents across project, user, and plugin layers
and provides similarity heuristics for detecting overlapping assets. Use when
generating skills or agents, detecting duplicate assets, or checking for name
collisions.
|
| domains | ["discovery","similarity","assets","duplicates"] |
Asset Discovery
Discovery Locations
Scan these locations for existing assets. Skip any layer whose directory does not exist.
| Layer | Skills | Agents |
|---|
| Project | .claude/skills/*/SKILL.md | .claude/agents/*.md |
| User | ~/.claude/skills/*/SKILL.md | ~/.claude/agents/*.md |
| Plugin | plugins/*/skills/*/SKILL.md | (none currently bundled) |
For each discovered asset, read its YAML frontmatter and extract name, description, domains, generated_by, and generated_at.
Presentation order: Group by type (skills, then agents). Within each type, sort by layer (project, user, plugin). Within each layer, sort alphabetically by name.
Source labels: Tag each discovered asset with its origin: [project], [user], [plugin:{name}].
If a discovery layer is inaccessible (missing directory, permissions error), warn once and continue with results from accessible layers. Warn more prominently for project-level failures.
Provenance Classification
Classify each discovered asset's provenance state based on frontmatter fields (see coding-workflows:agent-patterns for field definitions):
| State | Detection | Default Action |
|---|
| Generated | Has generated_by field | Suggest "Update" if stale, "Skip" if current (user always confirms) |
| Manually created | No generated_by field | Inform only (never offer overwrite) |
Edge case rules:
- Unparseable frontmatter: classify as "manually created" (existing fallback behavior)
generated_by present with unrecognized value: still classify as "generated" (informational, not validated)
Provenance tags in discovery output: Show [generated] or [manual] tags for [project]-layer assets only. User-layer and plugin-layer assets show without provenance tags.
Legacy Provenance Mapping
All generated_by values across versions map to the current generator. All values classify as "generated" for provenance purposes.
| Legacy Value | Era | Current Equivalent |
|---|
workflow-generate-agents | pre-v3 | generate-assets |
workflow-generate-skills | pre-v3 | generate-assets |
workflow-setup | pre-v3 | generate-assets |
generate-agents | v3 | generate-assets |
generate-skills | v3 | generate-assets |
setup | v3+ | generate-assets (when setup invokes generation internally) |
generate-assets | v4+ | (current) |
Domain-Comparison Staleness Detection
When a self-match is detected for a generated asset, compare the asset's domains array from frontmatter against the current analysis output's detected domains for that domain area:
Staleness signals (compare per-asset):
- New domains in analysis not in asset's `domains` array → stale
- Domains in asset's `domains` array no longer detected → stale
- Framework change since `generated_at` date → stale
- All domains still present and no new ones → current
This is asset-level comparison, not project-level. Each asset is evaluated against its own domain coverage. See coding-workflows:codebase-analysis for what constitutes meaningful staleness.
Note on computation: This staleness detection requires only comparing arrays and strings -- no cryptographic hashing. The LLM compares the asset's domains frontmatter against the domain list from the analysis output.
Tools-Comparison Staleness Detection
When a self-match is detected for a generated agent, compare the agent's tools field against the current template tools (the template is defined in the generator command, e.g., generate-assets). The tools field may be a comma-separated string or a YAML array; both are normalized to a set before comparison.
Tools staleness signals (agents only, not skills):
- Tools in template not in agent's `tools` list → stale (missing capabilities)
- Tools in agent's `tools` list not in template → informational (user addition or template removal)
- No explicit `tools` field → NOT stale (inherits all tools, superset of template)
- Empty `tools` field → treat as absent (skip comparison)
Skills do not have a tools field and are not evaluated for tools staleness (agents only, not skills).
Skills-Comparison Staleness Detection
When a self-match is detected for a generated agent, compare the agent's skills frontmatter array against the expected skills set. The expected set is the union of:
- Universal skills (required for execution-capable agents only -- those with
Write or Edit tools)
- Domain-matched skills (skills whose
domains overlap with the agent's domains)
Skills staleness signals (agents only, not skills):
- Universal skill missing from execution-capable agent's `skills` list → stale (missing universal)
- Universal skill absent from review-only agent's `skills` list → NOT stale (expected)
- Domain-matched skill absent from agent's `skills` list → stale (skills drift)
- Skill in agent's `skills` list no longer resolving to any layer → stale (dangling reference)
- Skill in agent's `skills` list present but not in expected set → informational (user addition)
- All expected skills present, no dangling refs → current
Universal vs domain distinction: The staleness summary must distinguish between these two categories. Missing universal skills on execution-capable agents indicate the agent predates a workflow upgrade. Missing domain skills indicate the project's skill inventory has grown since the agent was generated. Review-only agents are not evaluated for universal skill staleness.
Resolution order: Check universal skills first, then domain-matched skills. This ensures universal skill gaps are surfaced prominently.
Skills staleness is evaluated for agents only (not skills), since skills do not have a skills frontmatter field.
Provenance Summary
After the discovery table, present a provenance summary:
Provenance summary:
- N agents: X generated (Y stale), Z manual
- N skills: X generated (Y stale), Z manual
Keyword-Bag Construction
Build a keyword bag for each asset from three sources:
- Name: Split on hyphens. Exclude structural suffixes:
patterns, conventions, reviewer, specialist, architect.
- Domains: Array items as-is. If
domains is empty or missing, this source contributes nothing.
- Description: Split on whitespace, lowercase. Remove stop words:
the, a, an, for, and, or, with, to, from, that, this, which, is, are, was, were, be, been, use, when, how.
The keyword bag is the union of all three sources (deduplicated, lowercased).
Worked example: stack-patterns (proposed) vs coding-workflows:stack-detection [plugin:coding-workflows] (existing)
| Source | stack-patterns | coding-workflows:stack-detection |
|---|
| Name (minus suffixes) | stack | stack, detection |
| Domains | [stack, technology] | [detection, stack, technology, languages] |
| Description keywords | stack, conventions, projects, reviewing, code | discovers, technology, stack, detection, reference, tables |
| Keyword bag | {stack, technology, conventions, projects, reviewing, code} (6) | {stack, detection, technology, languages, discovers, reference, tables} (7) |
Intersection: {stack, technology} = 2. Overlap ratio: 2 / min(6, 7) = 0.33 → IGNORE (below 0.4). However, if descriptions share more vocabulary, the ratio rises — the threshold is tuned for real-world descriptions, not minimal examples.
Three-Tier Classification
| Tier | Condition | Action |
|---|
| BLOCK | Exact name match in any layer (same type or cross-type) | Must rename or skip. Refuse to generate. |
| WARN | Keyword-bag overlap ratio >= 0.4 | Present overlap evidence, offer: skip / rename / generate anyway. For generated assets, also offer: re-generate. |
| IGNORE | Below 0.4 threshold | No action. |
Overlap ratio: |intersection| / min(|A|, |B|) where A and B are the keyword bags of the proposed and existing assets. This is more robust than Jaccard for bags of different sizes -- a small bag fully contained in a larger bag scores 1.0.
Cross-type matching (skills vs agents): Same keyword-bag approach, same 0.4 threshold. A skill and agent covering the same domain is a valid pattern (e.g., api-patterns skill + api-reviewer agent). Only flag when keyword-bag overlap is genuinely high, and present as informational rather than a collision.
Self-Match Rule
When the proposed output path matches an existing asset's path exactly, this is a self-match (an update, not a duplicate). Always apply the self-match check before any collision check.
For self-matches, check the existing asset's provenance state and branch accordingly:
| # | State | UX |
|---|
| 1 | Generated + stale | Show domain-comparison staleness summary with evidence. Suggest Update (default). Offer: Skip, Show full proposed content. |
| 2 | Generated + current | "Asset is current (generated {date}). Skipping." |
| 3 | Manually created | "Not generated by workflow commands. Skipping." (Informational: analysis notes if relevant, e.g., "analysis detected overlapping domains: X, Y") |
Error paths:
- Frontmatter unparseable: treat as manually created
generated_by present but domains array empty/missing: skip staleness detection, offer "Update or skip?" (original self-match behavior)
Frontmatter Parse Failures
Assets without parseable YAML frontmatter:
- Identity fallback: Use parent directory name for skills (e.g.,
api-patterns from .claude/skills/api-patterns/SKILL.md), file stem for agents (e.g., api-reviewer from .claude/agents/api-reviewer.md).
- Keyword comparison: Include in exact-name matching only. Exclude from keyword-bag overlap (no
domains or description to extract).
True/False Positive Examples
| Proposed | Existing | Type Match | Result | Why |
|---|
stack-patterns | coding-workflows:stack-detection [plugin:coding-workflows] | same (skill) | WARN | Keyword bags share stack via name; descriptions likely share technology/detection |
db-patterns | data-patterns [project] | same (skill) | WARN | Descriptions both mention database/data; name-only heuristic would miss this |
issue-writer | coding-workflows:issue-workflow [plugin:coding-workflows] | same (skill) | IGNORE | Despite shared issue prefix, domains differ (requirements vs planning,execution) and descriptions diverge |
api-patterns | api-reviewer [project] | cross (skill vs agent) | WARN | Keyword bags share api + domain keywords; flagged as informational (valid pairing) |
auth-patterns | testing-patterns [project] | same (skill) | IGNORE | Only structural suffix patterns overlaps (excluded from bag); no keyword overlap |
Validation Checklist
For command implementers referencing this skill — verify these when integrating discovery into a generator command:
Related Skills
coding-workflows:agent-patterns -- Defines the agent frontmatter spec (name, domains, role) and provenance fields (generated_by, generated_at) that this skill reads during discovery. Reference for understanding what fields are available on discovered agents.coding-workflows:codebase-analysis -- Defines staleness evaluation criteria (what domain/framework changes constitute meaningful staleness). Referenced during domain-comparison staleness detection.
See references/token-budgets.md for token budget rationale, measurement methodology, and adjustment guidance for the skills context budget used in agent generation.
