Indexes files and maps semantic code relationships to improve graph-based navigation and AI context.

Install

mkdir -p .claude/skills/yams && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2538" && unzip -o skill.zip -d .claude/skills/yams && rm skill.zip

Installs to .claude/skills/yams

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Code indexing, exact/semantic search, graph-assisted code navigation, and project memory
88 charsno explicit “when” trigger
Intermediate

Key capabilities

  • →Indexes codebase for semantic search
  • →Maps relationships between code symbols
  • →Attaches metadata (owner/phase/task) to work items
  • →Visualizes dependency graphs
  • →Auto-updates index on file changes via watcher

How it works

Maintains a local knowledge graph database that maps code tokens and their context, updated by a background daemon.

Inputs & outputs

You give it
Natural language search or graph exploration command
You get back
Relevant code snippets or path relationship data

When to use yams

  • →Search code with semantic context
  • →Explore relationships between code symbols
  • →Track project memory across tasks
  • →Index new files for rapid lookup

About this skill

YAMS Skill (agent.md)

Quick Reference

# Status & Health
yams status                    # Check daemon and index status
yams daemon start              # Start background daemon
yams doctor                    # Diagnose issues

# Indexing
yams add <file>                # Index single file
yams add . -r --include "*.py" # Index directory recursively
yams watch                     # Auto-index on file changes

# Search (use grep first, search for semantic)
yams grep "pattern" --cwd .    # Code pattern search scoped to current project
yams grep -e "--flag" --cwd .  # Explicit pattern for leading '-' text
yams grep -g "*.cpp" "TODO"   # rg-style glob filtering
yams grep --minimal "TODO"     # Compact grep-style output
yams search "query"            # Semantic/hybrid search

# Hydrate/export a selected search result
yams cat --hash <hash>          # Inspect saved content on stdout
yams get --hash <hash> -o <path> # Export only when a file copy is needed

# Graph
yams graph --explore <file>    # KG-backed current-file snippets and incident edges
yams graph --name <file>       # Related documents of a file
yams graph --list-types        # List node types with counts
yams graph --relations         # List relation types with counts
yams graph --search "pattern"  # Search nodes by label
# graph owns path/tree/topology inspection; retired tree is not top-level

# Agent storage
yams list --format json        # Scriptable list output
yams list --show-metadata      # Include metadata for work item

Agent Memory Workflow

YAMS is the single source of truth for agent memory and work item.

Required Metadata (Task Tracking)

Attach metadata to every yams add.

  • task - short task slug (e.g., list-json-refresh)
  • phase - start | checkpoint | complete
  • owner - agent or author
  • source - code | note | decision | research

Index Project Files

# Index specific file types
yams add . -r --include "*.ts,*.tsx,*.js"

# Index with exclusions
yams add . -r --include "*.py" --exclude "venv/**,__pycache__/**"

# Index with metadata for tracking
yams add src/ -r --metadata "task=list-json-refresh,phase=checkpoint,owner=codex,source=code"

Auto-Index with Watch

yams watch                     # Start watching current directory
yams watch --interval 2000     # Custom interval (ms)
yams watch --stop              # Stop watching

Verify Indexing

yams status                    # Shows indexed file count
yams list --limit 10           # Recent indexed files

Search Patterns

Decision Tree

  1. Code patterns → yams grep (fast, regex/literal; use --cwd . for repo scoping)
  2. Semantic/concept → yams search (embeddings/hybrid)
  3. Selected-file context → yams graph --explore from a search/grep hit; for callers and related tests, use scoped grep or LSP
  4. Path/tree/topology inspection → use yams graph, not retired top-level tree
  5. No results from grep → Try yams search, then follow graph_explore_hint when present
  6. Saved memory content → search/list discovers candidates; yams cat --hash <hash> hydrates the selected artifact

Search, list, and grep snippets are routing context, not the complete saved memory. Hydrate the most relevant one to three note/decision/research/evidence hits before using them. For code hits, prefer graph narrowing plus a targeted local read instead of reading every result in full.

grep (Code Search)

# Exact pattern
yams grep "function authenticate"

# Regex pattern
yams grep "async.*await.*fetch"

# With context lines
yams grep "TODO" -A 2 -B 2

# Filter by extension
yams grep "import" --ext py

# rg-style glob filter (repeatable)
yams grep -g "src/**/*.cpp" "TODO"

# Compact grep-style output (default is richer agent context)
yams grep --minimal "TODO" -g "src/**/*.cpp"

# Scope to current working directory or an explicit directory
yams grep "TODO" --cwd .
yams grep "TODO" --cwd src/daemon

# Literal text (no regex)
yams grep "user?.name" -F

# Per-file match cap: --limit is an alias for -m/--max-count, not global
# Use search/list --limit for global result caps.
yams grep "TODO" -m 5

# Pattern starts with '-': use -- or explicit -e/--regexp
yams grep -- "--tags|foo" --include="docs/**/*.md"
yams grep --regexp "--tags|foo" -g "docs/**/*.md"

search (Semantic Search)

# Concept search
yams search "error handling patterns"

# Hybrid search (default)
yams search "authentication flow" --type hybrid

# Limit results
yams search "database connection" --limit 5

# Filter by file type
yams search "API endpoint" --ext ts

search (Metadata-Only)

# Force metadata/FTS path for structured metadata
yams search "task=example-task" --type keyword --limit 10

# Unique task selection (avoid collisions)
yams search "task=example-task" --type keyword --limit 20
# 2) List all used task values with counts

# Tag filters (tags are stored as metadata keys: tag:<name>)
yams search "plan" --type keyword --tags plan --limit 10
yams search "tagged logic" --type keyword --tags plan --limit 20

Agent Storage

Store Research

# Index documentation
curl -s "https://docs.example.com/api" | yams add - --name "api-docs.md" \
  --metadata "task=docs-cache,phase=checkpoint,owner=codex,source=research"

# Store with metadata
yams add notes.md --metadata "task=research-auth,phase=checkpoint,owner=codex,source=research"

Store Decisions

# Pipe decision record
echo "## Decision: Use JWT for auth

### Context
Need stateless authentication for microservices.

### Decision
JWT with RS256, 15min expiry, refresh tokens.

### Rationale
Stateless, scalable, industry standard.
" | yams add - --name "decision-jwt-auth.md" \
  --metadata "task=auth-decision,phase=checkpoint,owner=codex,source=decision"

Retrieve Knowledge

# Discover related decisions; results emit an exact cat command.
yams search "authentication decision" --limit 10

# Hydrate a selected saved-memory artifact before relying on it.
yams cat --hash <hash-from-result>

# Export only when a filesystem copy is needed.
yams get --hash <hash-from-result> -o <path>

# Find by exact metadata.
yams list --format json --show-metadata \
  --metadata "owner=codex" --metadata "task=example-task" \
  --metadata "source=decision" --limit 10

# Metadata + tags are separate in JSON output
yams list --format json --show-metadata \
  | jq '.documents[] | {name,metadata,tags}'

For CLI workflows, cat is the inspection/hydration hop and get -o is the export hop. For MCP workflows, chain search to get with include_content: true, as shown below.

Session Management

Create Work Sessions

# Start named session
yams session start --name "feature-auth"

# List sessions
yams session ls

# Switch session
yams session use "feature-auth"

# Show current session
yams session show --json

Session Scope

# Add files to session scope
yams session add --path "src/auth/**"

# Warm session cache (faster searches)
yams session warm --limit 100

# Search within session
yams search "login" --session

Session Lifecycle

# Save session state
yams session save

# Load previous session
yams session load --name "feature-auth"

# Clear session cache
yams session clear

# End session
yams session close

Graph Queries

Use search/grep to select a concrete file before graph exploration. Run from the repository root: explore scopes to the current working directory, not a detected repository root. Use --global only for an intentional cross-project query.

Agent Graph Context

# Follow a selected file, not a broad concept or ambiguous basename.
yams graph --explore src/auth/login.ts --max-files 3

# Preserve the absolute result path when projects contain the same relative path.
yams graph --explore /path/to/repo/src/auth/login.ts --max-files 3 --json
  • Search/grep may emit graph_explore_hint. Verify that its target names the selected file; a display-relative path is not proof of project identity. Hints for files outside the current directory include --global; execute these only when intentionally following that cross-project result.
  • Explore resolves existing KG labels/aliases, then hydrates bounded spans from current local files. It does not automatically select neighboring files from relationships or provide a complete definition/caller/test analysis.
  • Whole-file path/document versions share one hydration context per local path. Distinct segments and explicit spans retain their identities; relationships from contributing file nodes remain subject to the relationship budget. Candidate lookup is bounded, not an exhaustive inventory of matching nodes.
  • Inspect warnings, file modes, and truncated. --max-files limits snippet files; entry labels and relationship metadata also contribute to output size. A snippet is not a full-file read or an indexed snapshot.
  • An existing file can have no matching KG node. Empty output does not establish that the file, symbol, or caller is absent. Use a targeted local read/grep.
  • Unreadable local source cannot be hydrated by explore. Use yams cat --hash when an indexed snapshot is needed, and keep snapshot versus working-tree provenance explicit. Do not repair or reindex just to make a lookup succeed.

Raw Graph Structure

# List available node types and relation types
yams graph --list-types
yams graph --relations

# Search nodes by label pattern (wildcards: * any chars, ? single char)
yams graph --search "*Controller*"
yams graph --search "auth*"
yams graph --search "handle?Request"

# List document nodes whose paths are under the current directory
yams graph --list-type document --scope-cwd --limit 50

File Relationships

Automatic code-symbol extraction was removed in v0.20. Symbolic node/edge types can still exist in custom-inge


Content truncated.

When not to use it

  • →Searching for extremely small, non-indexed snippets
  • →Working in non-persistent ephemeral environments

Prerequisites

YAMS daemon installed

Limitations

  • →Initial indexing can be time-consuming
  • →Memory usage grows with project size
  • →Requires daemon to be running

How it compares

It uses semantic memory to navigate project relationships instead of simple regex searching.

Compared to similar skills

yams side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
yams (this skill)15moReviewIntermediate
scientific-brainstorming3711moNo flagsIntermediate
webclaw17moReviewIntermediate
graphify-knowledge-graph07moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

scientific-brainstorming

davila7

Research ideation partner. Generate hypotheses, explore interdisciplinary connections, challenge assumptions, develop methodologies, identify research gaps, for creative scientific problem-solving.

37155

webclaw

0xmassi

Web extraction engine with antibot bypass. Scrape, crawl, extract, summarize, search, map, diff, monitor, research, and analyze any URL — including Cloudflare-protected sites. Use when you need reliable web content, the built-in web_fetch fails, or you need structured data extraction from web pages.

14

graphify-knowledge-graph

Aradotso

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

00

markitdown

K-Dense-AI

Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing. Use when converting documents to markdown, extracting text from PDFs/Office files, transcribing audio, performing OCR on images, extracting YouTube transcripts, or processing batches of files. Supports 20+ formats including DOCX, XLSX, PPTX, PDF, HTML, EPUB, CSV, JSON, images with OCR, and audio with transcription.

177310

whisper

davila7

OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast transcription, or multilingual audio processing. Best for robust, multilingual ASR.

1165

devtu-optimize-skills

mims-harvard

Optimize ToolUniverse skills for better report quality, evidence handling, and user experience. Apply patterns like tool verification, foundation data layers, disambiguation-first, evidence grading, quantified completeness, and report-only output. Use when reviewing skills, improving existing skills, or creating new ToolUniverse research skills.

13

Search skills

Search the agent skills registry