Subagent Knowledge Profile Generator
Generate a persistent PROJECT-KNOWLEDGE.md that captures deep domain knowledge
about a codebase, designed to fit in a subagent prompt context window.
Locating your own reference files
Every references/*.md mention below is relative to this skill's own
install location, not to the project being profiled (--project) — your
working directory is the target project, so a bare relative path will not
resolve. Resolve it once, in one Bash call, at the top of the workflow:
SKILL_HOME=$(ls -d ~/.claude/plugins/cache/hideki-plugins/subagent-gen/*/skills/subagent-gen 2>/dev/null | sort -V | tail -1)
echo "$SKILL_HOME"
Re-derive $SKILL_HOME in the same Bash call as any later read — shell
state doesn't persist between separate Bash tool calls. This is also the
"skill resource dir" to pass to the synthesis subagent in Phase 3 (its own
input contract expects it as an absolute path, not a relative one).
Arguments
Parse these from the user's invocation. All are optional with defaults:
| Argument | Default | Description |
|---|
--project | cwd | Path to the project to profile |
--name | (auto) | Profile name — used as filename in ~/.claude/knowledge/. Auto-derived from manifest or directory name |
--output | ~/.claude/knowledge/{name}.md | Override the canonical output path |
--update | false | Refresh an existing profile incrementally |
--depth | standard | quick (~2K words), standard (~4K words), deep (~6K words) |
--focus | all | Comma-separated subset: structure, architecture, conventions, domain |
--list | false | List all available profiles in ~/.claude/knowledge/ and stop |
Workflow
Phase 0: List Profiles (if --list)
If --list is passed, list all *.md files in ~/.claude/knowledge/:
ls -la ~/.claude/knowledge/*.md 2>/dev/null
For each file, parse the header line to extract project name, generation date, depth, and
source path. Display as a table:
| Profile | Generated | Depth | Source Path |
|---|
| {name} | {date} | {depth} | {path} |
Then stop — do not proceed to profiling.
Feedback Check
If feedback/log.md exists and has 5 or more entries, read the last 10 entries.
If a pattern is apparent (same issue in 3+ entries, or average rating below 3):
- Tell the user: "Recurring feedback detected: [brief pattern]. Consider running
/skill-improve --skill subagent-gen."
- Continue with normal execution.
Phase 1: Identify Target Project
- Use
--project path or current working directory
- Verify it contains source files (not empty or config-only)
- Derive
--name if not provided:
- Read
package.json → use name field
- Read
pyproject.toml → use [project] name
- Read
Cargo.toml → use [package] name
- Fallback: use the directory basename, lowercased, hyphens for spaces
- If
--update, check for existing profile at ~/.claude/knowledge/{name}.md first,
then fall back to .agent/local/PROJECT-KNOWLEDGE.md
- Read
.gitignore to understand exclusion patterns
If the directory is empty or has no source files, report "No source files found" and stop.
Phase 2: Reconnaissance (Inline)
Quick inline scan — no subagents needed. Gather metadata for Phase 3.
- Read root manifests: Look for
package.json, pyproject.toml, Cargo.toml, go.mod,
pom.xml, build.gradle, *.sln, *.csproj, Gemfile, composer.json, mix.exs,
CMakeLists.txt, Makefile, Dockerfile, docker-compose.yml
- Directory tree: Use Glob/Bash to map top 3 levels of the directory tree
- File census: Count source files vs test files vs config files by extension
- Detect stack: From manifests, identify:
- Primary language(s) and version(s)
- Framework(s)
- Build system / package manager
- Test runner(s)
- Whether it's a monorepo (multiple package.json / workspace config)
Produce a metadata block in this format to pass to Phase 3 agents:
PROJECT METADATA
================
Name: {project name from manifest}
Path: {absolute path}
Language(s): {e.g., TypeScript 85%, Python 15%}
Framework(s): {e.g., Next.js 14, FastAPI}
Build: {e.g., pnpm, turborepo}
Test runner: {e.g., vitest, pytest}
Monorepo: {yes/no — packages: ...}
Source dirs: {e.g., src/, api/, packages/}
Test dirs: {e.g., __tests__/, tests/, e2e/}
File count: {e.g., 342 source, 89 test, 45 config}
Phase 3: Parallel Deep Exploration
Read "$SKILL_HOME"/references/exploration-dimensions.md for the full pattern catalog for each dimension.
Spawn Explore-type subagents in parallel. Each agent receives:
- The project path
- The metadata block from Phase 2
- Its specific exploration instructions from the dimension catalog
Agent Configuration by Depth
--depth=quick — 2 agents:
| Agent | Combined Dimensions |
|---|
| structure-architecture | Structure + Architecture: directory layout, entry points, module boundaries, how modules connect, data flow, layering |
| conventions-domain | Conventions + Domain: naming patterns, error handling, key abstractions, API surface, config |
--depth=standard — 4 agents:
| Agent | Dimension |
|---|
| structure-agent | Directory layout, entry points, module boundaries, build outputs |
| architecture-agent | Module connections, dependency graph, data flow, layering, state management |
| conventions-agent | Naming patterns, error handling, logging, validation, testing patterns |
| domain-agent | Business/domain concepts, key abstractions, API surface, configuration |
--depth=deep — 4 agents with expanded scope:
Same agents as standard, but each samples more files (20-30 instead of 10-15) and traces
deeper dependency chains. Architecture agent also maps middleware chains and plugin systems.
Agent Prompt Template
For each agent, construct a prompt like:
You are analyzing a codebase to build a deep knowledge profile.
PROJECT METADATA
================
{paste metadata block from Phase 2}
YOUR DIMENSION: {dimension name}
=================================
{paste the relevant section from "$SKILL_HOME"/references/exploration-dimensions.md}
INSTRUCTIONS:
- Explore the project at {project path}
- Follow the exploration patterns and grep signals listed above
- Sample {10-15 | 20-30} files across different directories
- For every finding, include the concrete file path and specific detail
- Do NOT include vague descriptions — every bullet must have a file path or function name
- Output your findings in the exact markdown format specified in the dimension catalog
Report back your findings as a structured markdown block.
Focus Filtering
If --focus is set to specific dimensions (e.g., --focus=structure,domain), only spawn agents
for those dimensions. Skip the others.
Monorepo Handling
If the project is a monorepo with multiple packages:
- Ask the user which package(s) to profile, or whether to profile the root structure
- If profiling specific packages, scope each agent's exploration to those package directories
- If profiling root, focus on workspace config, shared utilities, and cross-package patterns
Large Project Handling (>5000 files)
- Warn the user about project size
- Suggest using
--focus to narrow scope
- Instruct agents to use sampling: read representative files from each directory rather than
exhaustive scans
- Cap the number of files each agent reads to 30
Phase 4: Synthesize Profile (delegated)
Hand the metadata block + all collected agent findings to
@agent-subagent-gen:subagent-gen along with:
- target depth (
quick / standard / deep)
--focus filter--output path--update flag (if set)- the skill resource dir so the subagent can read
"$SKILL_HOME"/references/profile-template.md
and "$SKILL_HOME"/references/prompt-integration-guide.md
The subagent does the synthesis, quality-checks every bullet (every line
must carry a file path / identifier / pattern name / concrete value),
enforces word-count targets, preserves <!-- USER: ... --> blocks in
update mode, writes the profile to the canonical path, and creates the
.agent/local/PROJECT-KNOWLEDGE.md symlink (falling back to copy on
Windows without Developer Mode).
The subagent returns:
{
"profile_path_global": "~/.claude/knowledge/{name}.md",
"profile_path_local": ".agent/local/PROJECT-KNOWLEDGE.md",
"word_count": 4123,
"depth": "standard",
"sections_preserved_from_user": ["..."],
"key_findings": ["..."],
"gitignore_suggestion": ".agent/local/"
}
Phase 5: Present Summary
Use the subagent's return value to show the user:
- Profile name and word count
- Global path:
~/.claude/knowledge/{name}.md (accessible from any project)
- Local path:
.agent/local/PROJECT-KNOWLEDGE.md (symlinked for convenience)
- 3-5 key findings highlights (most interesting / non-obvious)
- If
gitignore_suggestion came back, mention adding .agent/local/ to
.gitignore
- How to use the profile (read
"$SKILL_HOME"/references/prompt-integration-guide.md):
- Same project:
Read .agent/local/PROJECT-KNOWLEDGE.md for context, then: <task>
- Cross-project:
Read ~/.claude/knowledge/{name}.md for context, then: <task>
- List all profiles:
/subagent-gen --list
Error Handling
| Situation | Behavior |
|---|
| Empty directory / no source files | Report and stop |
| Monorepo detected | Ask user which packages to focus on |
| Very large project (>5000 files) | Warn, suggest --focus, use sampling |
--update but no existing profile | Fall back to fresh generation |
| Agent exploration fails or times out | Report partial results, note incomplete dimensions |
| Unrecognized language/framework | Profile what can be inferred from file structure and naming |
| Symlink creation fails (Windows) | Copy the file instead, warn about manual sync |
--name conflicts with existing profile | Ask user to confirm overwrite or choose a different name |
~/.claude/knowledge/ doesn't exist | Create it automatically |
Retrospective
After completing the workflow, reflect on the entire execution session:
- Consider: Were there mid-session corrections? Rejected outputs? Plan changes? Errors?
- Ask the user: "Quick feedback on this run? (1-5 rating, note any issues, or press enter to skip)"
- If the user provides feedback OR if corrections/issues occurred during this session:
a. Create
feedback/ directory if it does not exist (header: # Feedback Log + blank
line + <!-- Append new entries at the top. Do not edit previous entries. -->)
b. Prepend a new entry after the header:
## <ISO-8601 timestamp>
- **Skill Version**: <version from this file's frontmatter>
- **Task**: <brief description>
- **Outcome**: success | partial-success | failure | error
- **Rating**: <N>/5 (or "—" if not provided)
- **Corrections**: <mid-session corrections, or "none">
- **Issues**: <specific problems, or "none">
- **User Note**: <user's verbatim feedback, or "—">
---
- If the user skips AND no corrections or issues occurred, end without recording.
Behavior Scenarios
Scenario: Generate fresh profile for a standard project
Given the user is in a project directory with source code and no existing profile
When the user says "profile this project" or "generate project knowledge"
Then the skill scans the project, launches parallel exploration agents,
synthesizes findings into PROJECT-KNOWLEDGE.md, saves to .agent/local/,
and shows how to use the profile in subagent prompts
Scenario: Update an existing profile after codebase changes
Given a PROJECT-KNOWLEDGE.md already exists in .agent/local/
When the user says "update project profile" or invokes with --update
Then the skill reads the existing profile, focuses exploration on changed files,
preserves user-customized sections (<!-- USER: ... -->), regenerates machine
sections, and shows what changed
Scenario: Quick profile for a small task
Given the user needs a lightweight profile fast
When the user says "quick project profile" or invokes with --depth=quick
Then the skill runs 2 combined agents, produces a ~2000-word profile,
and completes faster than standard depth
Scenario: Profile a specific project path (not cwd)
Given the user wants to profile a project in a different directory
When the user says "profile project at D:\Projects\my-app"
Then the skill uses the specified path as the project root for all exploration
Scenario: Very large monorepo project
Given the project has over 5000 files or is a monorepo with multiple packages
When the user invokes the skill
Then the skill warns about size, asks which packages to focus on (if monorepo),
uses sampling strategies to stay within token budget, and generates a profile
scoped to the selected packages
Scenario: Use a profile from another project
Given the user has profiled Project A and is now working in Project B
When the user spawns a subagent with "Read ~/.claude/knowledge/project-a.md for context"
Then the subagent has deep knowledge of Project A while working in Project B
Scenario: List all available profiles
Given the user has generated profiles for multiple projects
When the user says "list project profiles" or invokes with --list
Then the skill lists all profiles in ~/.claude/knowledge/ with name, date, and source path
References
"$SKILL_HOME"/references/exploration-dimensions.md — Pattern catalog for each exploration dimension (what to look for, grep signals, sampling strategy, output format)"$SKILL_HOME"/references/profile-template.md — Exact PROJECT-KNOWLEDGE.md template with section specs and placeholder examples"$SKILL_HOME"/references/prompt-integration-guide.md — How to load the generated profile into subagent prompts (inclusion patterns, selective loading, examples)