Analyze Project

Scan a project and produce or update

docs/TechStack.md

and

docs/ProjectStructure.md

— living documentation that any AI agent session can read to instantly understand the project without re-scanning from scratch.

When to Use

Starting work on a project for the first time
Before any feature work when project docs don't exist yet
Periodically to keep docs current after codebase changes
After major refactors, dependency upgrades, or service additions

When NOT to use:

docs/TechStack.md

and

docs/ProjectStructure.md

exist and no significant structural changes (config files, directories, container configs) have occurred since the last scan.

Input

A project or workspace root (provided by user or detected from workspace)

Output

```
docs/TechStack.md
```
— concise tech stack reference card
```
docs/ProjectStructure.md
```
— operational project map
In monorepos: per-service copies under
```
[service-path]/docs/
```

The Process

Step 1: Check Existing Docs

Check if

docs/TechStack.md

and

docs/ProjectStructure.md

exist at the project root.

If they exist, read them and extract the YAML frontmatter:

yaml

---
generated-by: analyze-project
date: 2024-03-14T12:00:00Z
commit: abc1234
---

If the files exist, hold their contents — you'll compare against fresh scan results later.

Step 2: Staleness Gate

Run

git rev-parse --short HEAD

to get the current commit hash.

If the

commit

field in frontmatter differs from HEAD (it usually will — it records the commit at last scan, not the latest), check what actually changed:

Run

git diff --name-only <frontmatter-commit>..HEAD

to get committed changes, and

git status --short

to get uncommitted changes (staged, unstaged, and untracked files). Combine both lists.

Evaluate whether the changes are significant for project docs:

Significant changes (trigger re-scan): new/removed/renamed config files (
```
package.json
```
,
```
composer.json
```
,
```
docker-compose.yml
```
,
```
Dockerfile
```
,
```
Makefile
```
,
```
*.config.*
```
, etc.), new/removed top-level directories, changes to
```
.devcontainer/
```
, CI config changes, README/INSTALL/SETUP changes
Insignificant changes (skip re-scan): source code changes within existing directories, test changes, asset changes, documentation changes in subdirectories

Decision:

Files don't exist → Proceed to scan.
Files exist, commits match HEAD → Report "Project docs are up to date." and stop.
Files exist, commits differ, only insignificant changes → Report "Project docs are up to date (no structural changes since last scan)." and stop.
Files exist, commits differ, significant changes detected → Report which files changed and proceed to scan.
No commit field in frontmatter → Proceed to scan.

If git is not available, skip this check and always proceed to scan.

Step 3: Ownership Check

For each existing file, check the

generated-by

field in YAML frontmatter:

generated-by: analyze-project
present → Skill owns this file. Will update without asking.
File exists but no
generated-by: analyze-project
→ Manually authored. Ask the user before overwriting:

"
docs/TechStack.md
exists but wasn't generated by this skill. Overwrite it? (yes/no)"

If user declines, skip that file and report findings in chat instead.

Step 4: Scan Root

List the project root directory. Read relevant files found:

Config files (reveal tech stack):

package.json

composer.json

Cargo.toml

go.mod

pyproject.toml

Gemfile

build.gradle

pom.xml

, etc.

tsconfig.json

vite.config.*

webpack.config.*

nuxt.config.*

, etc.

Container and dev environment:

```
docker-compose.yml
```
/
```
docker-compose.yaml
```
```
Dockerfile
```
```
.devcontainer/devcontainer.json
```

CI/CD:

```
.github/workflows/*.yml
```
```
.gitlab-ci.yml
```
```
Jenkinsfile
```

Documentation:

```
README.md
```
```
INSTALL.md
```
,
```
SETUP.md
```

Quality tooling:

```
Makefile
```
```
.eslintrc.*
```
,
```
eslint.config.*
```
```
.prettierrc
```

phpunit.xml

vitest.config.*

jest.config.*

pytest.ini

Start from the root listing. If root has enough config files, that's all you need. If root contains only a single folder (e.g., the repo wraps one project in a subdirectory), treat that folder as the effective root and list it instead. If root is unclear, run a quick glob for config files (

**/{*.yml,*.yaml,*.json,*.toml,*.ini,*.md}

) limited to a small number of results — the paths reveal where projects and services live (e.g.,

services/api/package.json

). Then read those directories. Avoid full recursive filesystem scans.

Step 5: Detect Monorepo

Check for monorepo signals from what was found in Step 4:

Directories named
```
apps/
```
,
```
services/
```
,
```
packages/
```
at root
```
docker-compose.yml
```
defining multiple services with build contexts

Workspace config in

package.json

(

workspaces

field) or

pnpm-workspace.yaml

Multiple
```
Dockerfile
```
references in different subdirectories

If monorepo detected, identify service directories and their names.

Step 6: Scan Services (monorepo only)

For each service directory identified in Step 5, apply the same root-reading approach:

List the service directory
Read its config files (package.json, composer.json, Dockerfile, etc.)
Read its README.md if present
Note its doc location, dev/lint/test commands

Step 7: Write Docs

Use the templates from

references/formats.md

Single project:

Write
```
docs/TechStack.md
```
with tech stack reference card
Write
```
docs/ProjectStructure.md
```
with operational project map
```
ProjectStructure.md
```
ends with a "See Also" link to
```
DatabaseStructure.md
```

Monorepo:

Write root
```
docs/TechStack.md
```
with shared stack + per-service summary
Write root
```
docs/ProjectStructure.md
```
with service table and monorepo-level overview

For each service, write

[service-path]/docs/TechStack.md

and

[service-path]/docs/ProjectStructure.md

Create
```
docs/
```
directories if they don't exist

All files get YAML frontmatter with:

```
generated-by: analyze-project
```
```
date:
```
current ISO 8601 datetime
```
commit:
```
current short git commit hash

Announce the saved paths:

"Project docs updated:
docs/TechStack.md
docs/ProjectStructure.md
[per-service paths if monorepo] Commit: [hash]"

Common Rationalizations

Rationalization	Reality
"The README has all this info"	READMEs describe intent and setup steps. TechStack and ProjectStructure describe current reality in a structured, machine-readable format.
"I can just read package.json"	One config file gives you one piece. These docs synthesize all signals into two quick-read files.
"The project is small, I don't need docs"	Small projects still have a stack, structure, and tooling. Two short files save every future session from re-discovering them.
"Docs will get outdated"	The staleness gate and commit tracking exist specifically to prevent this. Run the skill again.

Red Flags

Skipping the staleness check and always rewriting (wastes time, loses manual edits)
Deep-scanning the filesystem instead of reading root
Not including YAML frontmatter in output files
Overwriting manually-authored files without asking
Missing the monorepo detection step on a multi-service project
Writing rationale or opinions instead of facts in TechStack.md
Not creating
```
docs/
```
directory before writing

Verification

Before finishing, confirm:

Staleness check performed (or git unavailable noted)
Ownership check performed for existing files
Root directory listing read (not deep-scanned)
Relevant config files read
```
docs/TechStack.md
```
written with frontmatter and concise stack listing
```
docs/ProjectStructure.md
```
written with frontmatter and operational map
```
ProjectStructure.md
```
ends with reference to
```
DatabaseStructure.md
```
If monorepo: services detected and per-service docs written
All generated files have
```
generated-by
```
,
```
date
```
, and
```
commit
```
in frontmatter
Saved paths announced to user

analyze-project

NPX Install

Tags

SKILL.md Content