Architectural analysis workflow using Serena symbols and Forgetful memory. Use when analyzing project structure, documenting architecture, creating component entities, or building knowledge graphs from code.
Analyzes codebase architecture using Serena symbols and optionally persists findings to Forgetful knowledge graphs.
/plugin marketplace add rjmurillo/ai-agents/plugin install project-toolkit@ai-agentsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill guides systematic architectural analysis using Serena's symbol-level understanding, with optional persistence to Forgetful's knowledge graph.
| Trigger Phrase | Operation |
|---|---|
analyze the architecture of this project | Full 6-phase analysis workflow |
map out the codebase structure | Phase 1-3 discovery and component mapping |
trace dependencies for this component | Phase 4 dependency tracing |
create architecture memories | Phase 5-6 memory and entity creation |
what components does this project have | Phase 3 core component mapping |
Use this skill when:
Use using-serena-symbols instead when:
Understand the high-level layout:
# Get directory structure
mcp__plugin_serena_serena__list_dir({
"relative_path": ".",
"recursive": false
})
# Identify key directories (src/, app/, lib/, etc.)
mcp__plugin_serena_serena__list_dir({
"relative_path": "src",
"recursive": true
})
Goal: Identify entry points, main modules, and organizational patterns.
Find the application entry points:
# Look for main/app files
mcp__plugin_serena_serena__search_for_pattern({
"substring_pattern": "if __name__.*==.*__main__|def main\\(|app\\s*=\\s*FastAPI|createApp",
"restrict_search_to_code_files": true
})
# Get symbols from entry file
mcp__plugin_serena_serena__get_symbols_overview({
"relative_path": "src/main.py",
"depth": 1
})
Identify and analyze major components:
# Find all service/controller/model classes
mcp__plugin_serena_serena__find_symbol({
"name_path_pattern": "Service",
"substring_matching": true,
"include_kinds": [5], # Class only
"depth": 1
})
# For each major component, get full structure
mcp__plugin_serena_serena__find_symbol({
"name_path_pattern": "AuthService",
"include_body": false,
"depth": 1 # Get methods
})
Understand how components connect:
# Find who uses AuthService
mcp__plugin_serena_serena__find_referencing_symbols({
"name_path": "AuthService",
"relative_path": "src/services/auth.py"
})
# Find what AuthService depends on
mcp__plugin_serena_serena__find_symbol({
"name_path_pattern": "AuthService/__init__",
"include_body": true
})
Store findings in Forgetful:
# First, find/create the project
execute_forgetful_tool("list_projects", {"repo_name": "owner/repo"})
# Create memory for architectural insight
execute_forgetful_tool("create_memory", {
"title": "AuthService: Core authentication component",
"content": "AuthService handles JWT validation, user sessions, and OAuth flows. Dependencies: UserRepository, TokenService, CacheService. Used by: all API endpoints via middleware.",
"context": "Discovered during architectural analysis",
"keywords": ["auth", "jwt", "service", "architecture"],
"tags": ["architecture", "component"],
"importance": 8,
"project_ids": [PROJECT_ID]
})
Create entities for major components:
# Check if entity exists first
execute_forgetful_tool("search_entities", {"query": "AuthService"})
# Create component entity
execute_forgetful_tool("create_entity", {
"name": "AuthService",
"entity_type": "other",
"custom_type": "Service",
"notes": "Core authentication service - JWT, OAuth, sessions",
"tags": ["service", "auth"],
"project_ids": [PROJECT_ID]
})
# Create relationships
execute_forgetful_tool("create_entity_relationship", {
"source_entity_id": AUTH_SERVICE_ID,
"target_entity_id": USER_REPO_ID,
"relationship_type": "depends_on",
"strength": 0.9
})
# Link entity to memories
execute_forgetful_tool("link_entity_to_memory", {
"entity_id": AUTH_SERVICE_ID,
"memory_id": ARCH_MEMORY_ID
})
Standard relationship types for architecture:
| Type | Use For |
|---|---|
uses | General usage (A uses B) |
depends_on | Dependency (A requires B) |
calls | Direct function/method calls |
extends | Class inheritance |
implements | Interface implementation |
connects_to | External connections (DB, API) |
contains | Composition (A contains B) |
| Type | Use For |
|---|---|
Service | Business logic services |
Repository | Data access layer |
Controller | Request handlers |
Middleware | Request/response processing |
Model | Data models/entities |
Library | External dependencies |
Framework | Framework components |
# 1. Find routers
mcp__plugin_serena_serena__search_for_pattern({
"substring_pattern": "APIRouter\\(\\)|router\\s*=",
"restrict_search_to_code_files": true
})
# 2. Analyze router structure
mcp__plugin_serena_serena__get_symbols_overview({
"relative_path": "src/routers/users.py",
"depth": 1
})
# 3. Find dependency injection
mcp__plugin_serena_serena__search_for_pattern({
"substring_pattern": "Depends\\(",
"restrict_search_to_code_files": true,
"context_lines_before": 1,
"context_lines_after": 1
})
# 4. Trace service dependencies
mcp__plugin_serena_serena__find_referencing_symbols({
"name_path": "get_current_user",
"relative_path": "src/dependencies/auth.py"
})
# 5. Create architecture memory
execute_forgetful_tool("create_memory", {
"title": "FastAPI app structure: Routers + Dependencies",
"content": "App uses router-based organization with dependency injection. Routers: /users, /auth, /products. Dependencies: get_current_user, get_db. All routes require auth except /auth/login.",
"context": "FastAPI architecture analysis",
"keywords": ["fastapi", "router", "dependency-injection"],
"tags": ["architecture", "pattern"],
"importance": 8,
"project_ids": [PROJECT_ID]
})
| Avoid | Why | Instead |
|---|---|---|
| Analyzing every class as a component | Creates noise in entity graph | Focus on major architectural components only |
| Reading full source before overview | Wastes tokens on unneeded code | Start with get_symbols_overview, read selectively |
| Creating entities without memories | Entities lack context without linked knowledge | Create memory first, then entity, then link them |
| Skipping dependency tracing | Misses critical coupling relationships | Always run Phase 4 for components you create entities for |
| Documenting WHAT without WHY | Memories become stale quickly | Focus memories on rationale and trade-offs |
After architectural analysis:
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.