Skip to content

Commit 31e1aa1

Browse files
jerelvelardecursoragent
jerelvelarde
and
cursoragent
committed
Initial commit: Chalk agent skills and AGENTS.md templates
6 skills (setup-chalk, setup-docs, create-doc, update-doc, create-plan, product-context-docs) and 4 AGENTS.md variants for Claude Code and Cursor. Co-authored-by: Cursor <cursoragent@cursor.com>
0 parents  commit 31e1aa1

17 files changed

Lines changed: 932 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Chalk Skills
2+
3+
Agent skills that ship with [Chalk](https://github.com/chalk-pm) -- the product planning system for AI-enabled teams. These skills teach coding agents (Claude Code, Cursor, etc.) how to work with Chalk's documentation-as-product-truth model.
4+
5+
## What Are Chalk Skills?
6+
7+
Chalk skills are structured markdown instructions that agents read at runtime. Each skill gives an agent a specific capability: bootstrapping docs from a codebase, creating plans, updating documentation, or capturing a project's architecture and design system for style transfer.
8+
9+
Skills follow the `.claude/skills/` convention (Claude Code) and `.cursor/skills/` convention (Cursor) so they're auto-discovered by the agent when referenced or triggered.
10+
11+
## Repository Structure
12+
13+
```
14+
Chalk-skills/
15+
├── README.md
16+
├── skills/ # All Chalk agent skills
17+
│ ├── setup-chalk/SKILL.md # Full .chalk/ folder generation with style transfer
18+
│ ├── setup-docs/SKILL.md # One-shot profile doc bootstrap
19+
│ ├── create-doc/SKILL.md # Create new docs in .chalk/docs/
20+
│ ├── update-doc/SKILL.md # Update existing docs
21+
│ ├── create-plan/SKILL.md # Create .plan.md files
22+
│ └── product-context-docs/ # Cursor skill with templates
23+
│ ├── SKILL.md
24+
│ ├── agents/openai.yaml
25+
│ └── assets/templates/
26+
│ ├── product-profile.md
27+
│ ├── product-features.md
28+
│ ├── architecture.md
29+
│ ├── tech-stack.md
30+
│ └── sitemap.md
31+
└── agents-md/ # AGENTS.md files by project
32+
├── chalk-browser-AGENTS.md # Electron app (most comprehensive)
33+
├── chalk-cli-template-AGENTS.md # Template distributed by npx get-chalk
34+
├── chalk-design-partners-AGENTS.md # Design partner repos
35+
└── chalk-root-AGENTS.md # Monorepo root
36+
```
37+
38+
## Skill Inventory
39+
40+
### Claude Code Skills (`.claude/skills/`)
41+
42+
| Skill | Purpose | Trigger |
43+
|-------|---------|---------|
44+
| **setup-chalk** | Analyze a repo and generate the full `.chalk/` folder -- product profile, engineering profile, AI profile, design system, tech stack, coding style, brand assets | First-time project setup, style transfer |
45+
| **setup-docs** | One-shot bootstrap that populates all three profile stubs with real codebase content | After `npx get-chalk` or Chalk Browser init |
46+
| **create-doc** | Create a new numbered doc file in `.chalk/docs/` under the correct vertical | "Create a doc about..." |
47+
| **update-doc** | Update an existing doc -- find it, apply changes, bump the "Last updated" line | "Update the engineering profile..." |
48+
| **create-plan** | Create a `.plan.md` file with YAML frontmatter and actionable todos | "Plan the auth feature..." |
49+
50+
### Cursor Skills (`skills/`)
51+
52+
| Skill | Purpose | Trigger |
53+
|-------|---------|---------|
54+
| **product-context-docs** | Create and update `/docs` product context documentation (product profile, features, sitemap, architecture, tech stack) | "Document this product", "bootstrap /docs" |
55+
56+
### AGENTS.md Files
57+
58+
| File | Source | Description |
59+
|------|--------|-------------|
60+
| `chalk-browser-AGENTS.md` | `chalk-browser/` | Most comprehensive -- includes Electron conventions, IPC patterns, and inline plan creation instructions |
61+
| `chalk-cli-template-AGENTS.md` | `chalk-cli/templates/` | Template distributed to user repos via `npx get-chalk` -- generic Chalk conventions with plan creation |
62+
| `chalk-design-partners-AGENTS.md` | `Chalk-DesignPartners/` | Minimal version for design partner repos |
63+
| `chalk-root-AGENTS.md` | Root `/` | Monorepo-level instructions pointing to `.chalk/docs` |
64+
65+
## How Skills Are Structured
66+
67+
Each skill is a folder containing a `SKILL.md` file and optional supporting assets:
68+
69+
```
70+
skill-name/
71+
├── SKILL.md # Required -- agent instructions
72+
├── reference.md # Optional -- detailed docs
73+
├── examples.md # Optional -- usage examples
74+
└── assets/ # Optional -- templates, scripts
75+
└── templates/
76+
```
77+
78+
### SKILL.md Anatomy
79+
80+
Every `SKILL.md` has YAML frontmatter and a markdown body:
81+
82+
```markdown
83+
---
84+
name: skill-name
85+
description: What this skill does and when to use it
86+
allowed-tools: Read, Write, Glob, Grep
87+
argument-hint: "[what the user passes]"
88+
---
89+
90+
# Skill Title
91+
92+
## Workflow
93+
1. Step one...
94+
2. Step two...
95+
```
96+
97+
- `name` -- Unique identifier (lowercase, hyphens, max 64 chars)
98+
- `description` -- Drives auto-discovery; must include **what** and **when**
99+
- `allowed-tools` -- Restricts the agent to only the tools it needs
100+
- `argument-hint` -- Shows the user what to pass after the slash command
101+
102+
## Where Skills Live
103+
104+
Skills are placed in two locations depending on the agent:
105+
106+
| Agent | Path | Scope |
107+
|-------|------|-------|
108+
| Claude Code | `.chalk/.claude/skills/<skill-name>/` | Per-project |
109+
| Cursor | `.cursor/skills/<skill-name>/` | Per-project |
110+
| Cursor (personal) | `~/.cursor/skills/<skill-name>/` | All projects |
111+
112+
Chalk distributes skills inside `.chalk/.claude/skills/` so they travel with the `.chalk/` folder when it's initialized in a repo.
113+
114+
## The `.chalk/` Folder
115+
116+
Skills produce and maintain the `.chalk/` documentation structure:
117+
118+
```
119+
.chalk/
120+
├── chalk.json # Project metadata
121+
├── docs/
122+
│ ├── product/
123+
│ │ └── 0_PRODUCT_PROFILE.md # What, who, why
124+
│ ├── engineering/
125+
│ │ ├── 0_ENGINEERING_PROFILE.md # Read-this-first technical overview
126+
│ │ ├── 1_architecture.md # Process model, data flow, diagrams
127+
│ │ ├── 2_coding-style.md # Naming, patterns, conventions
128+
│ │ └── 3_techstack.md # Every dependency with version + purpose
129+
│ ├── ai/
130+
│ │ └── 0_AI_PROFILE.md # Agent orientation, gotchas, quick ref
131+
│ └── design/
132+
│ ├── 0_design-system.md # Colors, typography, spacing, tokens
133+
│ └── assets/ # Logos, icons, favicons
134+
└── .claude/
135+
└── skills/ # Skills that maintain the above
136+
```
137+
138+
### Doc Conventions
139+
140+
- No YAML frontmatter in docs (plain markdown only)
141+
- First `# Heading` is the document title
142+
- `Last updated: YYYY-MM-DD (<brief note>)` immediately after the title
143+
- Numbered filenames: `0_` for profiles, sequential for additional docs
144+
- Verticals: `product/` (business-facing), `engineering/` (technical), `ai/` (agent-facing), `design/` (visual)
145+
146+
## Design Principles
147+
148+
**Style transfer fidelity** -- An agent reading `.chalk/docs` should be able to write code that looks like it belongs in the codebase, place files in the right directories, use the correct libraries, and match the visual design.
149+
150+
**Concrete over abstract** -- Real hex codes, not "brand green." Real file paths, not "the components folder." Real code snippets from the actual repo.
151+
152+
**Generation creates options, approval creates truth** -- Skills generate documentation; humans review and approve it. Agents never silently merge generated content into project truth.
153+
154+
**Progressive disclosure** -- `SKILL.md` contains the essentials (under 500 lines). Detailed reference material lives in separate files linked from the skill.
155+
156+
## Adding a New Skill
157+
158+
1. Create a folder: `skills/<skill-name>/`
159+
2. Add a `SKILL.md` with frontmatter (`name`, `description`, `allowed-tools`, `argument-hint`)
160+
3. Write the workflow as numbered steps
161+
4. Add templates or scripts in `assets/` if needed
162+
5. Keep `SKILL.md` under 500 lines; use progressive disclosure for detail
163+
164+
### Naming
165+
166+
- Folder and `name` field: `kebab-case`, max 64 characters
167+
- Description: third-person, includes trigger terms
168+
- Filenames inside `.chalk/docs/`: `<number>_<snake_case_slug>.md`
169+
170+
## Related Projects
171+
172+
| Project | Description |
173+
|---------|-------------|
174+
| `chalk-cli` | CLI tool (`npx get-chalk`) that scaffolds `.chalk/` in any repo |
175+
| `chalk-browser` | Electron app for visual product planning and epic management |
176+
| `Chalk-DesignPartners` | Design partner program and feedback collection |
177+
178+
## License
179+
180+
MIT

‎agents-md/chalk-browser-AGENTS.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
<INSTRUCTIONS>
2+
Before planning or writing code in this repo, always read the existing docs in `.chalk/docs` and `README.md` to ground decisions in current product and technical context.
3+
4+
Key files to understand the codebase:
5+
- `.chalk/docs/product/0_PRODUCT_PROFILE.md` -- What the product is and does
6+
- `.chalk/docs/engineering/0_ENGINEERING_PROFILE.md` -- Architecture, tech stack, data flow
7+
- `.chalk/docs/ai/0_AI_PROFILE.md` -- AI-specific context, conventions, gotchas
8+
- `.chalk/.cursor/plans/0_roadmap.plan.md` -- Feature roadmap and completion status
9+
10+
Critical conventions:
11+
- Electron app with main process, preload scripts, and React renderer
12+
- Tab management via WebContentsView (Electron 30+)
13+
- Capture pipeline runs in main process, injects JS into tab webContents
14+
- UI follows atomic design: atoms -> molecules -> organisms
15+
- Tailwind CSS only, no CSS modules or styled-components
16+
- State management via React hooks + Electron IPC, no global state library
17+
- IndexedDB via Dexie.js for persistence (in renderer)
18+
- IPC communication via contextBridge (preload) and ipcMain.handle/ipcRenderer.invoke
19+
- If `.chalk/docs` is updated, keep `0_PRODUCT_PROFILE`, `0_ENGINEERING_PROFILE`, and `0_AI_PROFILE` in sync
20+
21+
## Skill: Create a Plan
22+
23+
When the user asks to "create a plan", "make a plan", "write a plan", or similar:
24+
25+
### 1. Determine the next plan number
26+
Read filenames in `.chalk/.cursor/plans/` (root level only, not subfolders). Find the highest numeric prefix. The new plan number = highest + 1. If no numbered files exist, start from 1.
27+
28+
### 2. Write the plan file
29+
Save to `.chalk/.cursor/plans/<number>_<snake_case_slug>.plan.md` using this format:
30+
31+
```
32+
---
33+
name: Short Plan Title
34+
overview: One-sentence description of what this plan delivers and why.
35+
todos:
36+
- id: kebab-case-id
37+
content: "Brief task description"
38+
status: pending
39+
- id: another-task
40+
content: "Another task"
41+
status: pending
42+
---
43+
44+
# Plan Title
45+
46+
## Objective
47+
48+
1-2 paragraphs describing the goal. The first paragraph is extracted by
49+
the parser as the plan's objective summary (up to 200 chars).
50+
51+
## Architecture
52+
53+
Technical approach. Include a Mermaid diagram if multi-component.
54+
55+
## File Changes
56+
57+
### 1. Component or Module Name
58+
59+
What changes, why, and key details.
60+
61+
## Key Design Decisions
62+
63+
- **Decision** -- Rationale
64+
```
65+
66+
### Rules
67+
- **Frontmatter is required** for new plans. It must include `name`, `overview`, and `todos`.
68+
- **Todos** use `status: pending | in_progress | done`. Start all as `pending`.
69+
- **Every plan must have** a `# Heading` and a `## Objective` section in the markdown body.
70+
- New plans go into the **root** of `.chalk/.cursor/plans/` (unsorted backlog), not a subfolder.
71+
- After writing, confirm the filename and give a brief summary.
72+
</INSTRUCTIONS>

‎agents-md/chalk-cli-template-AGENTS.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
<!-- chalk:start -->
2+
<INSTRUCTIONS>
3+
Before planning or writing code in this repo, always read the existing docs in `.chalk/docs` and `README.md` to ground decisions in current product and technical context. If `.chalk/docs` does not exist yet, create it using the repo's standard structure or note the gap before proceeding.
4+
5+
Key files to understand the codebase:
6+
- `.chalk/docs/product/0_PRODUCT_PROFILE.md` -- What the product is and does
7+
- `.chalk/docs/engineering/0_ENGINEERING_PROFILE.md` -- Architecture, tech stack, data flow
8+
- `.chalk/docs/ai/0_AI_PROFILE.md` -- AI-specific context, conventions, gotchas
9+
10+
Critical conventions:
11+
- If `.chalk/docs` is updated, keep `0_PRODUCT_PROFILE`, `0_ENGINEERING_PROFILE`, and `0_AI_PROFILE` in sync
12+
13+
## Skill: Create a Plan
14+
15+
When the user asks to "create a plan", "make a plan", "write a plan", or similar:
16+
17+
### 1. Determine the next plan number
18+
Read filenames in `.chalk/.cursor/plans/` (root level only, not subfolders). Find the highest numeric prefix. The new plan number = highest + 1. If no numbered files exist, start from 1.
19+
20+
### 2. Write the plan file
21+
Save to `.chalk/.cursor/plans/<number>_<snake_case_slug>.plan.md` using this format:
22+
23+
```
24+
---
25+
name: Short Plan Title
26+
overview: One-sentence description of what this plan delivers and why.
27+
todos:
28+
- id: kebab-case-id
29+
content: "Brief task description"
30+
status: pending
31+
- id: another-task
32+
content: "Another task"
33+
status: pending
34+
---
35+
36+
# Plan Title
37+
38+
## Objective
39+
40+
1-2 paragraphs describing the goal. The first paragraph is extracted by
41+
the parser as the plan's objective summary (up to 200 chars).
42+
43+
## Architecture
44+
45+
Technical approach. Include a Mermaid diagram if multi-component.
46+
47+
## File Changes
48+
49+
### 1. Component or Module Name
50+
51+
What changes, why, and key details.
52+
53+
## Key Design Decisions
54+
55+
- **Decision** -- Rationale
56+
```
57+
58+
### Rules
59+
- **Frontmatter is required** for new plans. It must include `name`, `overview`, and `todos`.
60+
- **Todos** use `status: pending | in_progress | done`. Start all as `pending`.
61+
- **Every plan must have** a `# Heading` and a `## Objective` section in the markdown body.
62+
- New plans go into the **root** of `.chalk/.cursor/plans/` (unsorted backlog), not a subfolder.
63+
- After writing, confirm the filename and give a brief summary.
64+
</INSTRUCTIONS>
65+
<!-- chalk:end -->

‎agents-md/chalk-design-partners-AGENTS.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<INSTRUCTIONS>
2+
Before planning or writing code in this repo, always read the existing docs in `.chalk/docs` and `README.md` to ground decisions in current product and technical context.
3+
4+
Key files to understand the codebase:
5+
- `.chalk/docs/product/0_PRODUCT_PROFILE.md` -- What the product is and does
6+
- `.chalk/docs/engineering/0_ENGINEERING_PROFILE.md` -- Architecture, tech stack, data flow
7+
- `.chalk/docs/ai/0_AI_PROFILE.md` -- AI-specific context, conventions, gotchas
8+
9+
## Skill: Create a Plan
10+
11+
When the user asks to "create a plan", "make a plan", or similar:
12+
13+
1. Read filenames in `.chalk/.cursor/plans/` (root only) to find the highest numbered plan. New number = highest + 1.
14+
2. Write to `.chalk/.cursor/plans/<number>_<slug>.plan.md` with YAML frontmatter (name, overview, todos) and markdown body (# Title, ## Objective, ## Architecture, ## File Changes, ## Key Design Decisions).
15+
3. All todos start as `pending`. Every plan needs a `# Heading` and `## Objective`.
16+
</INSTRUCTIONS>

‎agents-md/chalk-root-AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<INSTRUCTIONS>
2+
Before planning or writing code in this repo, always read the existing docs in `.chalk/docs` and `README.md` to ground decisions in current product and technical context. If `.chalk/docs` does not exist yet, create it using the repo's standard structure or note the gap before proceeding.
3+
</INSTRUCTIONS>

0 commit comments

Comments
 (0)