project-health

Name: project-health
Author: jezweb

1.4kinstalls96forks

How to install project-health?

jezweb/claude-skills/project-health

$npx -y skills add jezweb/claude-skills --skill project-health

Installs into the current project.

Summary

All-in-one project configuration and health management. Sets up new projects (settings.local.json, CLAUDE.md, .gitignore), audits existing projects (permissions, context quality, MCP coverage, leaked secrets, stale docs), tidies accumulated cruft, captures session learnings, and

Files · 1

View on GitHub

SKILL.md

1	# Project Health
2
3	One skill for everything about your project's Claude Code configuration. Run it at the start, middle, or end of a project — it figures out what's needed.
4
5	Goal: Zero permission prompts, well-organised context files, no cruft.
6
7	## When to Use
8
9	\| You say... \| What happens \|
10	\|-----------\|-------------\|
11	\| "project health" / "check project" \| Full audit: permissions + context + docs \|
12	\| "setup project" / "kickoff" / "bootstrap" \| New project setup from scratch \|
13	\| "tidy permissions" / "clean settings" \| Fix permissions file only \|
14	\| "capture learnings" / "update CLAUDE.md" \| Save session discoveries \|
15	\| "add python" / "add docker permissions" \| Add a preset to existing settings \|
16	\| "audit context" / "audit memory" \| Context-focused audit only \|
17
18	## Architecture: Sub-Agents
19
20	Heavy analysis runs in sub-agents to keep the main conversation clean. The main agent orchestrates; sub-agents do the scanning and return summaries.
21
22	### Agent 1: Permission Auditor
23
24	Launched with `Task(subagent_type: "general-purpose")`. Prompt:
25
26	```
27	Read .claude/settings.local.json.
28
29	Discover connected MCP servers: Use ToolSearch (search "mcp") and extract unique
30	server prefixes from tool names (e.g. mcp__vault__secret_list → vault).
31
32	Discover installed skills: Use the Skill tool or ToolSearch to list available skills.
33	For each skill that has scripts/ in its directory, note what Bash patterns it needs
34	(python3, env var prefixes like GEMINI_API_KEY=*, etc.). Check the SKILL.md for any
35	MCP tools the skill references (e.g. mcp__vault__secret_get).
36
37	Report:
38	1. MCP servers connected but NOT in settings (missing)
39	2. MCP servers in settings but NOT connected (stale)
40	3. Skill permissions: Bash patterns and MCP tools that installed skills need but aren't approved
41	4. File access: check for Read/Edit/Write patterns for .claude/ and //tmp/
42	in project settings, and ~/Documents//~/.claude/ in global settings
43	5. Leaked secrets: entries containing API keys, tokens, bearer strings, hex >20 chars, base64 >20 chars
44	6. Legacy colon syntax: entries like Bash(git:) instead of Bash(git )
45	7. Junk entries: shell fragments (Bash(do), Bash(fi), Bash(then), Bash(else), Bash(done)),
46	__NEW_LINE_* artefacts, loop body fragments (Bash(break), Bash(continue), Bash(echo *))
47	8. Duplicates: entries covered by a broader pattern (e.g. Bash(git add ) redundant if Bash(git ) exists)
48	9. Missing presets: based on files present, suggest presets from [permission-presets.md]
49
50	Prefer Read/Glob/Grep tools over Bash. If you need to scan multiple files or
51	run 3+ commands for one analysis, write a Python script to .jez/scripts/
52	and run it once (mkdir -p .jez/scripts first).
53
54	Return a structured summary, not raw data.
55	```
56
57	### Agent 2: Context Auditor
58
59	Launched with `Task(subagent_type: "general-purpose")`. Prompt:
60
61	```
62	Audit the project context landscape at [repo-path]:
63
64	1. Find all CLAUDE.md files. For each:
65	- Count lines (target: root 50-150, subdirs 15-50)
66	- Score quality on 6 criteria (see quality-criteria.md)
67	- Check for stale file/path references
68	- Flag oversized files
69
70	2. Find .claude/rules/ topic files. Check sizes (target: 20-80 lines).
71
72	3. Detect project type from files present (see project-types.md).
73	Check expected docs exist (ARCHITECTURE.md, DATABASE_SCHEMA.md, etc.)
74
75	4. Find public markdown (README.md, LICENSE, CONTRIBUTING.md).
76	Check for overlap with CLAUDE.md content.
77
78	5. Check auto-memory at ~/.claude/projects/*/memory/MEMORY.md
79
80	6. If Cloudflare project: find all wrangler.jsonc/wrangler.toml files.
81	Check each has "observability": { "enabled": true }. Flag any missing it.
82
83	Prefer Read/Glob/Grep tools over Bash. If you need to scan many files or
84	aggregate data across the repo, write a Python script to .jez/scripts/
85	and run it once rather than running many individual bash commands
86	(mkdir -p .jez/scripts first).
87
88	Return: project type, quality scores, missing docs, stale refs, overlaps,
89	size violations, observability gaps, and total markdown footprint.
90	```
91
92	### Parallel Execution
93
94	For a full health check, launch both agents in parallel:
95
96	```
97	Task(subagent_type: "general-purpose", name: "permission-audit", prompt: "...")
98	Task(subagent_type: "general-purpose", name: "context-audit", prompt: "...")
99	```
100
101	Both return summaries. The main agent combines them into on

People who liked this also viewed

6 picks

Type

project-health

1.4kinstalls96forks

View on GitHub

How to install project-health?

jezweb/claude-skills/project-health

$npx -y skills add jezweb/claude-skills --skill project-health

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Project Health
2
3	One skill for everything about your project's Claude Code configuration. Run it at the start, middle, or end of a project — it figures out what's needed.
4
5	Goal: Zero permission prompts, well-organised context files, no cruft.
6
7	## When to Use
8
9	\| You say... \| What happens \|
10	\|-----------\|-------------\|
11	\| "project health" / "check project" \| Full audit: permissions + context + docs \|
12	\| "setup project" / "kickoff" / "bootstrap" \| New project setup from scratch \|
13	\| "tidy permissions" / "clean settings" \| Fix permissions file only \|
14	\| "capture learnings" / "update CLAUDE.md" \| Save session discoveries \|
15	\| "add python" / "add docker permissions" \| Add a preset to existing settings \|
16	\| "audit context" / "audit memory" \| Context-focused audit only \|
17
18	## Architecture: Sub-Agents
19
20	Heavy analysis runs in sub-agents to keep the main conversation clean. The main agent orchestrates; sub-agents do the scanning and return summaries.
21
22	### Agent 1: Permission Auditor
23
24	Launched with `Task(subagent_type: "general-purpose")`. Prompt:
25
26	```
27	Read .claude/settings.local.json.
28
29	Discover connected MCP servers: Use ToolSearch (search "mcp") and extract unique
30	server prefixes from tool names (e.g. mcp__vault__secret_list → vault).
31
32	Discover installed skills: Use the Skill tool or ToolSearch to list available skills.
33	For each skill that has scripts/ in its directory, note what Bash patterns it needs
34	(python3, env var prefixes like GEMINI_API_KEY=*, etc.). Check the SKILL.md for any
35	MCP tools the skill references (e.g. mcp__vault__secret_get).
36
37	Report:
38	1. MCP servers connected but NOT in settings (missing)
39	2. MCP servers in settings but NOT connected (stale)
40	3. Skill permissions: Bash patterns and MCP tools that installed skills need but aren't approved
41	4. File access: check for Read/Edit/Write patterns for .claude/ and //tmp/
42	in project settings, and ~/Documents//~/.claude/ in global settings
43	5. Leaked secrets: entries containing API keys, tokens, bearer strings, hex >20 chars, base64 >20 chars
44	6. Legacy colon syntax: entries like Bash(git:) instead of Bash(git )
45	7. Junk entries: shell fragments (Bash(do), Bash(fi), Bash(then), Bash(else), Bash(done)),
46	__NEW_LINE_* artefacts, loop body fragments (Bash(break), Bash(continue), Bash(echo *))
47	8. Duplicates: entries covered by a broader pattern (e.g. Bash(git add ) redundant if Bash(git ) exists)
48	9. Missing presets: based on files present, suggest presets from [permission-presets.md]
49
50	Prefer Read/Glob/Grep tools over Bash. If you need to scan multiple files or
51	run 3+ commands for one analysis, write a Python script to .jez/scripts/
52	and run it once (mkdir -p .jez/scripts first).
53
54	Return a structured summary, not raw data.
55	```
56
57	### Agent 2: Context Auditor
58
59	Launched with `Task(subagent_type: "general-purpose")`. Prompt:
60
61	```
62	Audit the project context landscape at [repo-path]:
63
64	1. Find all CLAUDE.md files. For each:
65	- Count lines (target: root 50-150, subdirs 15-50)
66	- Score quality on 6 criteria (see quality-criteria.md)
67	- Check for stale file/path references
68	- Flag oversized files
69
70	2. Find .claude/rules/ topic files. Check sizes (target: 20-80 lines).
71
72	3. Detect project type from files present (see project-types.md).
73	Check expected docs exist (ARCHITECTURE.md, DATABASE_SCHEMA.md, etc.)
74
75	4. Find public markdown (README.md, LICENSE, CONTRIBUTING.md).
76	Check for overlap with CLAUDE.md content.
77
78	5. Check auto-memory at ~/.claude/projects/*/memory/MEMORY.md
79
80	6. If Cloudflare project: find all wrangler.jsonc/wrangler.toml files.
81	Check each has "observability": { "enabled": true }. Flag any missing it.
82
83	Prefer Read/Glob/Grep tools over Bash. If you need to scan many files or
84	aggregate data across the repo, write a Python script to .jez/scripts/
85	and run it once rather than running many individual bash commands
86	(mkdir -p .jez/scripts first).
87
88	Return: project type, quality scores, missing docs, stale refs, overlaps,
89	size violations, observability gaps, and total markdown footprint.
90	```
91
92	### Parallel Execution
93
94	For a full health check, launch both agents in parallel:
95
96	```
97	Task(subagent_type: "general-purpose", name: "permission-audit", prompt: "...")
98	Task(subagent_type: "general-purpose", name: "context-audit", prompt: "...")
99	```
100
101	Both return summaries. The main agent combines them into on

People who liked this also viewed

6 picks

Type