forge-setup-project

Name: forge-setup-project
Author: mgratzer

31installs5forks

How to install forge-setup-project?

mgratzer/forge/forge-setup-project

$npx -y skills add mgratzer/forge --skill forge-setup-project

Installs into the current project.

Summary

Set up or update a project's context infrastructure for agentic engineering — AGENTS.md as lean hot memory, docs/ as earned warm memory, with signal-to-noise scoring for existing guidance. Use when starting a new project, retrofitting an existing codebase, or auditing current gui

Files · 1

View on GitHub

SKILL.md

1	# Set Up or Update Project Context Infrastructure
2
3	Set up or update a project's context infrastructure for agentic engineering. Context is organized in three tiers:
4
5	\| Tier \| File(s) \| Role \|
6	\|------\|---------\|------\|
7	\| 1 — Hot memory \| AGENTS.md \| Always loaded. Lean, convention-dense. Only what agents need constantly. \|
8	\| 2 — Warm memory \| docs/*.md \| Loaded on-demand by topic. Created only when content earns its token cost. \|
9	\| 3 — Cold memory \| Specs, schemas, runbooks \| On-demand references for complex projects. Not created by this skill. \|
10
11	Central principle: context must earn its token cost. Only include knowledge that agents cannot discover by exploring the codebase with Grep, Glob, and Read.
12
13	`CLAUDE.md` is a compatibility symlink to `AGENTS.md`, never a separate source of truth.
14
15	## Input
16
17	Optional project root path (defaults to cwd). Optional: `-- <additional context>` for execution guidance.
18
19	## Process
20
21	### Step 1: Determine Mode
22
23	Scan the project root for `AGENTS.md`, `CLAUDE.md`, `README.md`, and `docs/`.
24
25	\| Mode \| Trigger \| Behavior \|
26	\|------\|---------\|----------\|
27	\| Setup \| Neither `AGENTS.md` nor `CLAUDE.md` exists \| Generate tiered context from scratch \|
28	\| Audit & Update \| `AGENTS.md` exists \| Score existing guidance, identify improvements, apply changes \|
29	\| Legacy Migration \| `CLAUDE.md` exists but `AGENTS.md` does not \| Migrate `CLAUDE.md` to `AGENTS.md`, then update \|
30
31	### Step 2: Explore the Codebase
32
33	Skip for greenfield projects (no code exists).
34
35	Explore thoroughly: structure, language/runtime, scripts, CI/CD, lint/format/test config, docs. Classify each finding as discoverable (agents can find it) or requires documentation (decisions, conventions, failure modes). Only the second category belongs in context files.
36
37	Assess agent readiness: feedback loops (tests, linter, build cycle speed), module structure (entry points, boundaries), app legibility (bootable locally?), known risks.
38
39	### Step 3: Audit Existing Guidance (Audit & Legacy Migration modes only)
40
41	Read all existing guidance files. Score each section:
42
43	\| Criterion \| Test \|
44	\|-----------\|------\|
45	\| Specificity \| Does this describe THIS project, or could it apply to any project? \|
46	\| Undiscoverability \| Would an agent find this by exploring? If yes, it's wasted context. \|
47	\| Currency \| Does this match the current codebase? Verify commands, paths, patterns. \|
48	\| Signal density \| Ratio of actionable information to total words? \|
49
50	Present an audit report. Group recommendations into quick wins, high-value additions, and structural changes. Get user confirmation via AskUserQuestion before applying.
51
52	### Step 4: Gather Project Information
53
54	Use AskUserQuestion to collect what cannot be determined from code.
55	Incorporate any optional additional context when deciding what to ask, audit, or prioritize.
56
57	Always ask:
58
59	1. Core principles — "What 3-5 rules should always guide development?" Offer examples from what you observed.
60	2. Failure modes — "What mistakes do agents or new developers repeat? What breaks?" Each entry must trace to an observed mistake.
61	3. Domain invariants — "What rules must never be violated? What causes silent bugs?"
62
63	Ask only if ambiguous from code:
64
65	4. Conventions with enforcement mechanisms
66	5. Confirm detected commands if multiple options exist
67	6. How to handle existing meta files (if found without `AGENTS.md`)
68
69	Never ask what's discoverable from code — language, framework, test runner, scripts, directory structure.
70
71	For Audit/Migration modes, ask about gaps found in Step 3.
72
73	### Step 5: Generate or Update AGENTS.md
74
75	Create or update `AGENTS.md`. Target ~150-200 lines. Every line must pass the undiscoverability test.
76
77	See [agents-md-template.md](references/agents-md-template.md) for the template structure.
78
79	For Legacy Migration: migrate accepted content into `AGENTS.md`, fold duplicates, replace legacy file with symlink in Step 7.
80
81	### Step 6: Generate or Update Tier 2 — docs/
82
83	Only create docs with actual content. An empty doc wastes context.
84
85	Always created:
86
87	- `docs/architecture.md` — design decisions, data flow, module responsibilities. Not directory listings.
88	- `docs/pr-workflow.md` — branch naming, PR checklist, review process. Reference AGENTS.md for commit format.
89
90	Created only when warranted (offer via AskUserQuestion based on detection):
91
92	- `docs/development.md` — when setup has gotchas or multi-step requirements
93	- `docs/coding-guidelines.md` — when project has specific patterns worth c

People who liked this also viewed

6 picks

Type

forge-setup-project

31installs5forks

View on GitHub

How to install forge-setup-project?

mgratzer/forge/forge-setup-project

$npx -y skills add mgratzer/forge --skill forge-setup-project

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Set Up or Update Project Context Infrastructure
2
3	Set up or update a project's context infrastructure for agentic engineering. Context is organized in three tiers:
4
5	\| Tier \| File(s) \| Role \|
6	\|------\|---------\|------\|
7	\| 1 — Hot memory \| AGENTS.md \| Always loaded. Lean, convention-dense. Only what agents need constantly. \|
8	\| 2 — Warm memory \| docs/*.md \| Loaded on-demand by topic. Created only when content earns its token cost. \|
9	\| 3 — Cold memory \| Specs, schemas, runbooks \| On-demand references for complex projects. Not created by this skill. \|
10
11	Central principle: context must earn its token cost. Only include knowledge that agents cannot discover by exploring the codebase with Grep, Glob, and Read.
12
13	`CLAUDE.md` is a compatibility symlink to `AGENTS.md`, never a separate source of truth.
14
15	## Input
16
17	Optional project root path (defaults to cwd). Optional: `-- <additional context>` for execution guidance.
18
19	## Process
20
21	### Step 1: Determine Mode
22
23	Scan the project root for `AGENTS.md`, `CLAUDE.md`, `README.md`, and `docs/`.
24
25	\| Mode \| Trigger \| Behavior \|
26	\|------\|---------\|----------\|
27	\| Setup \| Neither `AGENTS.md` nor `CLAUDE.md` exists \| Generate tiered context from scratch \|
28	\| Audit & Update \| `AGENTS.md` exists \| Score existing guidance, identify improvements, apply changes \|
29	\| Legacy Migration \| `CLAUDE.md` exists but `AGENTS.md` does not \| Migrate `CLAUDE.md` to `AGENTS.md`, then update \|
30
31	### Step 2: Explore the Codebase
32
33	Skip for greenfield projects (no code exists).
34
35	Explore thoroughly: structure, language/runtime, scripts, CI/CD, lint/format/test config, docs. Classify each finding as discoverable (agents can find it) or requires documentation (decisions, conventions, failure modes). Only the second category belongs in context files.
36
37	Assess agent readiness: feedback loops (tests, linter, build cycle speed), module structure (entry points, boundaries), app legibility (bootable locally?), known risks.
38
39	### Step 3: Audit Existing Guidance (Audit & Legacy Migration modes only)
40
41	Read all existing guidance files. Score each section:
42
43	\| Criterion \| Test \|
44	\|-----------\|------\|
45	\| Specificity \| Does this describe THIS project, or could it apply to any project? \|
46	\| Undiscoverability \| Would an agent find this by exploring? If yes, it's wasted context. \|
47	\| Currency \| Does this match the current codebase? Verify commands, paths, patterns. \|
48	\| Signal density \| Ratio of actionable information to total words? \|
49
50	Present an audit report. Group recommendations into quick wins, high-value additions, and structural changes. Get user confirmation via AskUserQuestion before applying.
51
52	### Step 4: Gather Project Information
53
54	Use AskUserQuestion to collect what cannot be determined from code.
55	Incorporate any optional additional context when deciding what to ask, audit, or prioritize.
56
57	Always ask:
58
59	1. Core principles — "What 3-5 rules should always guide development?" Offer examples from what you observed.
60	2. Failure modes — "What mistakes do agents or new developers repeat? What breaks?" Each entry must trace to an observed mistake.
61	3. Domain invariants — "What rules must never be violated? What causes silent bugs?"
62
63	Ask only if ambiguous from code:
64
65	4. Conventions with enforcement mechanisms
66	5. Confirm detected commands if multiple options exist
67	6. How to handle existing meta files (if found without `AGENTS.md`)
68
69	Never ask what's discoverable from code — language, framework, test runner, scripts, directory structure.
70
71	For Audit/Migration modes, ask about gaps found in Step 3.
72
73	### Step 5: Generate or Update AGENTS.md
74
75	Create or update `AGENTS.md`. Target ~150-200 lines. Every line must pass the undiscoverability test.
76
77	See [agents-md-template.md](references/agents-md-template.md) for the template structure.
78
79	For Legacy Migration: migrate accepted content into `AGENTS.md`, fold duplicates, replace legacy file with symlink in Step 7.
80
81	### Step 6: Generate or Update Tier 2 — docs/
82
83	Only create docs with actual content. An empty doc wastes context.
84
85	Always created:
86
87	- `docs/architecture.md` — design decisions, data flow, module responsibilities. Not directory listings.
88	- `docs/pr-workflow.md` — branch naming, PR checklist, review process. Reference AGENTS.md for commit format.
89
90	Created only when warranted (offer via AskUserQuestion based on detection):
91
92	- `docs/development.md` — when setup has gotchas or multi-step requirements
93	- `docs/coding-guidelines.md` — when project has specific patterns worth c

People who liked this also viewed

6 picks

Type