# Kiwi Home AI Coding Resources Asset Discovery

> Asset Discovery

- Skill: `tomevault-io/kiwi-home-ai-coding-resources-asset-discovery` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kiwi-home-ai-coding-resources-asset-discovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kiwi-home-ai-coding-resources-asset-discovery/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kiwi-home-ai-coding-resources-asset-discovery

---


# 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:
1. **Universal skills** (required for execution-capable agents only -- those with `Write` or `Edit` tools)
2. **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:

1. **Name:** Split on hyphens. Exclude structural suffixes: `patterns`, `conventions`, `reviewer`, `specialist`, `architect`.
2. **Domains:** Array items as-is. If `domains` is empty or missing, this source contributes nothing.
3. **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:

- [ ] Frontmatter parsed successfully from discovered asset (or fallback applied)
- [ ] Self-match check applied before collision check
- [ ] Same-type vs cross-type distinction noted in output
- [ ] Source layer label attached to each discovered asset
- [ ] User presented with concrete keyword overlap evidence (not numeric scores)
- [ ] Inaccessible layers warned, not failed
- [ ] Provenance state shown for project-layer assets
- [ ] Domain-comparison staleness evaluated for generated self-matches
- [ ] Tools-Comparison staleness evaluated for generated agent self-matches (agents only, not skills)
- [ ] Skills-Comparison staleness evaluated for generated agent self-matches (agents only, not skills)
- [ ] Skills staleness distinguishes universal (missing workflow upgrade) from domain (inventory growth)
- [ ] Reference integrity: agent `skills` frontmatter entries resolve to existing skills (project, user, or plugin layer). Unresolvable auto-populated refs are removed; unresolvable user-specified refs produce a warning. Dangling `skills` references are an additional staleness signal.

## 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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kiwi-home) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->