archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-04-09 Updated 2026-04-09

Forge Skill Cleanup Spec

Requirements: Forge_Skill_Cleanup_Requirements.md

0. Department Structure

Definition

A department is a root-level folder representing an organizational function. Departments are the top-level organizational unit in the repo. Every root-level folder (except dotfiles and infrastructure like .internal, .vscode, .github) is a department.

Canonical Departments (in order)

#	Department	Purpose
1	`Forge`	The agentic system and projects to implement it
2	`Uvilo`	The organization this instance of Forge serves
3	`Product`	Uvilo’s main product, Uvilo AI
4	`Technology`	Engineering, infrastructure, architecture
5	`Marketing`	Marketing strategy, content, campaigns
6	`Planning`	Strategic planning, roadmaps, OKRs
7	`Operations`	Day-to-day operations, HR, legal
8	`Finance`	Financial planning, budgets, reporting
9	`Investors`	Investor relations, fundraising, pitch materials

Required Structure

Every department MUST contain:

Department/
├── README.md             # Human-readable overview (no word budget, not agent-loaded)
├── AGENTS.md             # Machine-readable: agent instructions, file TOC, cross-references
├── Projects/             # Department-scoped projects
├── Skills/               # Department-scoped reusable procedures
└── Knowledge/            # Department-scoped reference material

README.md — Long-form human-readable overview of the department. Contains context, rationale, and narrative that humans need. No word budget. Not loaded by agents by default.

AGENTS.md — The machine-readable entry point for agents. Contains: a one-line description of the department, a TOC of files with one-line descriptions and paths, cross-references to relevant knowledge in other departments (especially Forge/Knowledge/), and any department-specific agent instructions. Word budget: ≤300 words.

Projects/ — Each project follows the standard project structure (see §0.2).

Skills/ — Department-scoped skills. Same structure as Forge-level skills (Skill_Name/SKILL.md). These contain procedures specific to this department that don’t belong in Forge.

Knowledge/ — Department-scoped reference material. Same rules as Forge-level knowledge (one topic per file, ≤800 words).

File Naming Convention

All file and folder names MUST be prefixed with the department or project name, except for the three infrastructure files: README.md, and AGENTS.md.

Examples:

Marketing/Marketing_Strategy.md ✅
Marketing/strategy.md ❌ (missing prefix)
Product/Projects/Taxonomy/Taxonomy_State.md ✅
Product/Projects/Taxonomy/state.md ❌ (missing prefix)

The sidebar menu structure in .internal/astro.config.mjs MUST mirror the folder structure. Menu item labels should match folder/file names (with underscores replaced by spaces). Exceptions: INDEX, README, and AGENTS entries may use simplified labels.

Current State & Migration

Current hollow departments (Finance, Investors, Marketing, Operations, Planning, Technology) each contain only a single department.md file (e.g., Finance/finance.md). Uvilo has content.md.

Migration:

For each department, create the required structure (README.md, AGENTS.md, Projects/, Skills/, Knowledge/)
Migrate content from existing department.md files into the new README.md
Delete the old department.md files
Update sidebar entries to match the new structure

Project Structure (unchanged, restated for clarity)

Projects follow the same pattern as departments but live inside Department/Projects/Project_Name/:

Project_Name/
├── README.md                      # Human-readable overview
├── AGENTS.md                      # Machine-readable entry point
├── Project_Name_State.md          # Living progress doc
├── Project_Name_History.md        # Compressed session summaries
├── Project_Name_WIP.md            # Session scratchpad (gitignored)
├── Project_Name_Spec.md           # Specification (if applicable)
├── Project_Name_Requirements.md   # Requirements (if applicable)
├── Project_Name_Research.md       # Research (if applicable)
├── Projects/                      # Sub-projects (if applicable)
├── Skills/                        # Project-scoped skills
└── Knowledge/                     # Project-scoped reference material

Not all files are required for every project. INDEX, README, and AGENTS are required. State/History/WIP are required for active projects.

1. Skill vs. Knowledge Boundary

Definition

Concept	Definition	Test
Skill	A reusable procedure — a sequence of steps an agent follows to accomplish a task. Has a trigger (when to use it) and produces a verifiable outcome.	”Can I walk through this step-by-step?”
Knowledge	A reference fact — domain information, constants, tool quirks, architectural context. No procedure; you look it up, you don’t execute it.	”Would I grep for this to answer a question?”
Command	A user-facing invocation mechanism — a `/name` shortcut that dispatches to a skill. Some commands point to skills with dedicated folders (e.g., `/deploy-config` → `Deploy_Config/`); others are lightweight procedures described inline in the commands table of `FORGE.md`. Commands are not content — they are dispatch entries.	”Does this just route the user to a procedure?”

Decision rule: If the content tells you how to do something (steps, commands, scripts, decision trees), it’s a skill. If it tells you what something is (facts, constants, constraints, reference tables), it’s knowledge. If a document contains both, extract the procedural part into a skill and keep the reference part in knowledge.

Edge cases:

Content	Classification	Reason
Tool quirks/workarounds	Knowledge (`Knowledge/Tools/<Tool>.md`)	Referenced on demand, not a procedure
Operational lessons	Knowledge (`LESSONS.md`)	Accumulated facts about what works
”How to create a page”	Skill	Step-by-step procedure with verifiable outcome
”Which files appear on the site” (glob rules)	Knowledge	Reference fact about content inclusion
”How to run the generator”	Skill	Procedure with commands and expected output
”What the generator produces” (categories, formats)	Knowledge	Declarative description of output
`/deploy-config`	Command → points to `Deploy_Config` skill	Dispatch entry, not standalone content
`/compact-history`	Command → inline procedure in `FORGE.md` commands table	Lightweight; no dedicated skill folder
`/git-status`	Command → points to `Git_Status` skill	Dispatch entry to a full skill

LESSONS.md Deprecation Path

LESSONS.md files have a tendency to accumulate stale entries. The long-term plan:

Root Forge/Lessons.md stays for now as a small cross-cutting file (≤300 words). Items should be reviewed monthly and either graduated to a Knowledge file or deleted if no longer relevant.
Skill-level LESSONS.md — stable lessons should be merged into SKILL.md. LESSONS.md is a staging area, not a permanent home. When SKILL.md is updated to incorporate a lesson, delete it from LESSONS.md.
Add a “review and prune” step to the end-of-session workflow: before ending a session, check if any lessons logged during the session should be promoted or deleted.

Where to record the boundary definition

Add a Skills vs. Knowledge subsection to FORGE.md under the PERSISTENT KNOWLEDGE section. Keep it to ~50 words — just the definition table and decision rule, not the edge cases. The edge cases live here in the Spec.

2. Placement & Size Limits

Current state

Placement rules and size budgets are already defined in FORGE.md:

Skills/ — Skill_Name/SKILL.md + optional LESSONS.md, scripts/, references/
Context budgets table with word limits per file type

Gaps found

Gap	Fix
No rule for when a Knowledge file should be split	Add: “One topic per file. Split when >800 words or when content covers two distinct subjects.”
No rule for skill folder naming	Add: “Skill folders use `Title_Case_With_Underscores` matching the repo-wide convention.”
No rule for what goes in `references/` vs inline in SKILL.md	Add: “Deep reference material (API docs, library tables, extended examples) goes in `references/`. SKILL.md contains only the procedure outline and essential rules needed to execute it.”
`create_new_version` and `markdown_to_pdf` use lowercase folder names	Rename to `Create_New_Version` and `Markdown_To_PDF`

Where to record

Add a Skill structure subsection to FORGE.md (under PERSISTENT KNOWLEDGE or a new SKILLS section). Keep it concise (~60 words). The full rationale lives here in the Spec.

3. Extract & Atomize Uncaptured Content

3.1 Source: AI_Guide.md (1,743 words)

Current location: Forge/Knowledge/AI_Guide.md

Problem: AI_Guide.md mixes procedural content (how to create a page, how to run the generator, how to add a sidebar group) with reference content (content inclusion rules, supported file types, key files reference). Per the skill/knowledge boundary, the procedural parts belong in skills.

Proposed extraction:

Content in AI_Guide.md	Classification	Destination
§ Project page generation system — “How it works” (categories, supported extensions)	Knowledge	Stay in `AI_Guide.md` (trimmed)
§ Running the generator manually	Skill	New skill: `Skills/Page_Generator/SKILL.md`
§ Creating a new page (Steps 1-4)	Skill	New skill: `Skills/Create_Page/SKILL.md`
§ Content inclusion rules (glob patterns, excluded dirs)	Knowledge	Stay in `AI_Guide.md`
§ Adding a new sidebar group	Skill	Merge into `Skills/Create_Page/SKILL.md` (it’s step 2.5 of creating a page)
§ Writing content (Markdown features, typography, internal links)	Knowledge	Stay in `AI_Guide.md`
§ Browser Automation (Playwright)	Knowledge	Move to `Knowledge/Tools/Playwright.md` (already exists — merge)
§ Key files reference	Knowledge	Stay in `AI_Guide.md`

Resulting AI_Guide.md: ~600 words — reference-only (generation system overview, content inclusion rules, writing/content conventions, key files table).

New skills produced:

Skills/Page_Generator/SKILL.md — When and how to run the project page generator, what it produces, when regeneration is needed.
Skills/Create_Page/SKILL.md — Step-by-step: create file with frontmatter → add sidebar entry → build → commit. Includes sidebar group creation as a sub-procedure.

3.2 Source: Uvilo_OS_To_Forge_Spec.md (1,557 words)

Current location: Forge/Projects/Uvilo_OS_To_Forge/Uvilo_OS_To_Forge_Spec.md

Problem: This Spec is a project document — it describes what was built. But several sections define rules that are now canonical and should be extractable as standalone reference or skill files, independent of the migration project.

Proposed extraction:

Section	Classification	Destination	Rationale
§4.1 UPPERCASE Infrastructure Files	Knowledge	`Knowledge/File_Naming.md` (new)	Naming convention used repo-wide
§4.2 INDEX.md / README.md Split	Knowledge	`Knowledge/File_Naming.md`	Part of naming conventions
§4.3 Project Sidebar Naming and Order	Knowledge	`Knowledge/File_Naming.md`	Currently buried in Spec
§4.4 AGENTS.md	Knowledge	`Knowledge/File_Naming.md`	Naming convention
§4.5 Project-Scoped Subdirectories	Knowledge	`Knowledge/File_Naming.md`	Standard project structure
§3 System Prompt Architecture	Knowledge	`Knowledge/System_Prompt.md` (new)	Three-layer pipeline, caching strategy
§5 Memory Architecture	Knowledge	`Knowledge/Memory_Architecture.md` (new)	File-based vs per-user memory split
§6 Word-Count Budgets	Knowledge	Already in FORGE.md	Confirm consistency; no extraction needed
§7 File Discovery Convention	Knowledge	Already in FORGE.md	Confirm consistency; no extraction needed
§8 Key Path Updates Required	Project-specific	Stay in Spec	Only relevant to migration
§9 Out of Scope	Project-specific	Stay in Spec	Only relevant to migration
§1 Goal, §2 Target Repository Structure	Project-specific	Stay in Spec	Historical context

New knowledge files produced:

Knowledge/File_Naming.md — UPPERCASE convention, INDEX/README split, sidebar naming order, AGENTS.md, project subdirectories (~400 words)
Knowledge/System_Prompt.md — Three-layer pipeline, caching, FORGE.md inlining (~300 words)
Knowledge/Memory_Architecture.md — File-based memory table, per-user memory config, skill-level LESSONS.md (~350 words)

3.3 Source: Hollow Department Folders

Current state: Finance, Investors, Marketing, Operations, Planning, Technology each have a single department.md file. Uvilo has content.md.

Action for each department:

Create INDEX.md, README.md, AGENTS.md
Create empty Projects/, Skills/, Knowledge/ directories (with .gitkeep if needed)
Migrate content from existing department.md / content.md into README.md
Delete the old file
Add sidebar entries

3.4 Other sources to check

Source	Status	Action
`Knowledge/libre_agents.md`	Already atomic	None — good example of proper knowledge file
`Knowledge/Setup.md`	Already atomic	None — infrastructure reference, properly placed
`Knowledge/Constants.md`	Already atomic	None — path constants, properly placed
`Knowledge/Tools/*.md`	Already atomic	None — per-tool quirks, properly placed

4. Fix Broken Artifacts Skill

Current state

Forge/Skills/Artifacts/SKILL.md (364 words) contains a reasonably complete technical reference for the artifact directive syntax, types, and React library table. It was reconstructed from the original LibreChat prompt but is missing several items.

Comparison with original (Original_Artifact_Instructions.md):

Content in original	In current SKILL.md?	Action
When to use artifacts (good/bad criteria)	❌ Missing	Add to SKILL.md as trigger section
Usage notes (one per message, prefer inline, simplicity)	❌ Missing	Add as “General Rules” section
Directive syntax format	✅ Present	Keep
Identifier rules (kebab-case, reuse for updates)	✅ Present	Keep
Title attribute	✅ Present	Keep
Type: text/html rules (no external images, cdnjs only)	✅ Present	Keep
Type: image/svg+xml rules (viewBox, no width/height)	✅ Present	Keep
Type: text/markdown rules	✅ Partial	Add note that both `text/markdown` and `text/md` accepted
Type: application/vnd.mermaid	✅ Present	Keep
Type: application/vnd.react rules	✅ Present	Keep
React libraries table	✅ Present	Keep
”No other libraries” rule	✅ Present	Keep
General rules (complete content, no truncation, err on side of not creating)	❌ Missing	Add
Examples (Mermaid, React, HTML)	❌ Missing (has one example)	Move extended examples to `references/`
”If asked to generate an image, offer SVG”	❌ Missing	Add to trigger section
shadcn/ui import path rule	✅ Present	Keep

Reconstructed SKILL.md structure

# Artifacts Skill

## When to Use (trigger)
- Substantial, self-contained content (>15 lines)
- Content user will modify or iterate on
- Standalone content usable outside conversation
- NOT for: short snippets, explanations, commentary, one-off questions
- One artifact per message unless requested
- Prefer inline when possible; err on side of not creating

## Directive Syntax
(keep existing)

## Types
(keep existing, add text/md alias note)

## General Rules
- Always provide complete, specific, fully functional content
- No snippets, placeholders, ellipses, or "remains the same"
- Reuse identifier for updates; new identifier for new artifacts
- If unsure whether content qualifies, err on side of not creating
- Never use triple backticks to enclose the artifact block itself

## Example
(keep one concise example in SKILL.md)

Extended examples → Forge/Skills/Artifacts/references/examples.md (Mermaid flowchart, React counter, HTML blog post from original).

Size check

Current SKILL.md: 364 words. Budget: ≤500 words. The reconstructed version with trigger + general rules should fit within budget. Extended examples go to references/.

5. Skill Folder Renames

Current lowercase skill folders violate the repo-wide Title_Case_With_Underscores convention:

Current	Target
`Skills/create_new_version/`	`Skills/Create_New_Version/`
`Skills/markdown_to_pdf/`	`Skills/Markdown_To_PDF/`

All other skill folders already use Title Case.

Dependencies to update:

Sidebar entries in .internal/astro.config.mjs (slug paths change)
Any cross-references in other files (grep for create_new_version and markdown_to_pdf)
FORGE.md commands table (no skill paths there, but verify)

6. Knowledge Index Update

After all extractions and new files are created, update Forge/Knowledge/index.md to include:

File_Naming — UPPERCASE convention, INDEX/README split, sidebar order, project structure
System_Prompt — Three-layer pipeline, caching, FORGE.md inlining
Memory_Architecture — File-based vs per-user memory, skill-level LESSONS.md
AI_Guide — Updated description (reference-only, no longer contains procedures)

Remove or update any entries that no longer match their file’s content.

7. Execution Order

Dependencies between tasks determine the sequence:

§0 (Dept structure) ──┐
                      ├──→ §1 (Define boundary) ──→ §3 (Extract & atomize) ──→ §2 (Verify limits)
                      │                                      │
                      │                                      ├──→ §3.3 (Scaffold departments)
                      │                                      │
                      └──────────────────────────────────────→ §4 (Fix Artifacts)
                                                              │
                                                              └──→ §5 (Renames) ──→ §6 (Index update)

§0 first — Define department structure and naming conventions. Everything else depends on this.
§1 second — The skill/knowledge definition is needed before classifying content.
§3 third — Extract content from AI_Guide.md and Uvilo_OS_To_Forge_Spec.md. Scaffold department folders.
§2 fourth — After extraction, verify placement rules and size limits.
§4 fifth — Fix the Artifacts skill.
§5 sixth — Rename lowercase skill folders.
§6 last — Update knowledge index to reflect all changes.

8. Files Produced

New files

File	Type	Source
`Forge/Skills/Page_Generator/SKILL.md`	Skill	Extracted from AI_Guide.md
`Forge/Skills/Create_Page/SKILL.md`	Skill	Extracted from AI_Guide.md
`Forge/Knowledge/File_Naming.md`	Knowledge	Extracted from Uvilo_OS_To_Forge_Spec §4
`Forge/Knowledge/System_Prompt.md`	Knowledge	Extracted from Uvilo_OS_To_Forge_Spec §3
`Forge/Knowledge/Memory_Architecture.md`	Knowledge	Extracted from Uvilo_OS_To_Forge_Spec §5
`Forge/Skills/Artifacts/references/examples.md`	Reference	Extracted from Original_Artifact_Instructions.md
`{Dept}/INDEX.md` (×7)	Infrastructure	New for each hollow department
`{Dept}/README.md` (×7)	Infrastructure	Content from old `department.md` files
`{Dept}/AGENTS.md` (×7)	Infrastructure	New for each hollow department

Updated files

File	Change
`Forge/Knowledge/AI_Guide.md`	Trimmed — procedures removed
`Forge/Skills/Artifacts/SKILL.md`	Restored missing sections
`Forge/FORGE.md`	Add skill/knowledge boundary, skill structure rules, department definition
`Forge/Knowledge/index.md`	New entries for extracted files

Renamed

From	To
`Forge/Skills/create_new_version/`	`Forge/Skills/Create_New_Version/`
`Forge/Skills/markdown_to_pdf/`	`Forge/Skills/Markdown_To_PDF/`

Deleted

File	Replacement
`Finance/finance.md`	`Finance/README.md`
`Investors/investors.md`	`Investors/README.md`
`Marketing/marketing.md`	`Marketing/README.md`
`Operations/operations.md`	`Operations/README.md`
`Planning/planning.md`	`Planning/README.md`
`Technology/technology.md`	`Technology/README.md`
`Uvilo/content.md`	`Uvilo/README.md`

9. Knowledge Discoverability (dependency)

Problem

File-based knowledge has a discoverability ceiling. An agent can only find a knowledge file if:

It’s linked from a file the agent has already loaded (e.g., INDEX.md, AGENTS.md)
The agent runs a glob or grep search with the right terms

This means knowledge that isn’t explicitly cross-referenced is effectively invisible. Cross-department discovery is particularly weak — an agent working in Product/Projects/ has no mechanism to discover relevant knowledge in Technology/ or Forge/Knowledge/ without reading every AGENTS.md first.

Short-term mitigations (this project)

Every department AGENTS.md MUST cross-reference relevant knowledge from other departments, especially Forge/Knowledge/
The Forge-level AGENTS.md should list all cross-cutting knowledge files

Long-term solution: TypeSense + MCP

The existing TypeSense project (see Forge/Projects/TypeSense/) is scoped as a website search UI replacement. It needs to be expanded to also serve as the agent knowledge discovery layer:

MCP server wrapping Typesense — agents call search_knowledge(query="file naming conventions") to find relevant files across the entire repo
CLI tool for humans to search from the terminal
Repo-wide indexing — index ALL markdown files in the repo, not just published website pages
Semantic + keyword hybrid search — agents can search by concept, not just exact terms

This is specified in detail in the updated TypeSense Research document. The Skill Cleanup project does not depend on TypeSense being complete, but full knowledge discoverability does.

10. Verification Checklist

After all changes:

Department structure:

All 9 departments exist with INDEX.md, README.md, AGENTS.md
All departments have Projects/, Skills/, Knowledge/ directories
All old department.md files are deleted and content migrated to README.md
Department definition added to FORGE.md
Sidebar structure mirrors folder structure

Naming:

All file/folder names follow prefix convention (except INDEX/README/AGENTS)
All skill folders use Title_Case_With_Underscores
Renamed folders have updated sidebar slugs and cross-references

Skill/Knowledge boundary:

Every skill has a SKILL.md ≤500 words
Every knowledge file is ≤800 words and covers one topic
No procedural content remains in knowledge files (AI_Guide.md, new knowledge files)
No reference-only content remains in skill files
FORGE.md contains the skill/knowledge boundary definition and skill structure rules

Content extraction:

AI_Guide.md is reference-only (~600 words)
Page_Generator and Create_Page skills exist and are complete
File_Naming, System_Prompt, Memory_Architecture knowledge files exist
Artifacts SKILL.md includes trigger, general rules, and all type details from original
Extended artifact examples exist in references/

Index and discovery:

Knowledge/index.md lists all knowledge files with accurate one-line descriptions
Every department AGENTS.md cross-references relevant Forge/Knowledge files
All new files have sidebar entries in astro.config.mjs

Build:

Build succeeds: cd .internal && npm run build

Forge Skill Cleanup Spec

0. Department Structure

Definition

Canonical Departments (in order)

Required Structure

File Naming Convention

Sidebar Mirroring

Current State & Migration

Project Structure (unchanged, restated for clarity)

1. Skill vs. Knowledge Boundary

Definition

LESSONS.md Deprecation Path

Where to record the boundary definition

2. Placement & Size Limits

Current state

Gaps found

Where to record

3. Extract & Atomize Uncaptured Content

3.1 Source: AI_Guide.md (1,743 words)

3.2 Source: Uvilo_OS_To_Forge_Spec.md (1,557 words)

3.3 Source: Hollow Department Folders

3.4 Other sources to check

4. Fix Broken Artifacts Skill

Current state

Reconstructed SKILL.md structure

Size check

5. Skill Folder Renames

6. Knowledge Index Update

7. Execution Order

8. Files Produced

New files

Updated files

Renamed

Deleted

9. Knowledge Discoverability (dependency)

Problem

Short-term mitigations (this project)

Long-term solution: TypeSense + MCP

10. Verification Checklist