AI Knowledge Harvester

Collect AI documentation into a centralized private ai-knowledge repository. Two modes, same output: classified, frontmattered markdown in a two-tier project taxonomy.

Capabilities

Parameters

For Mode 2 (ad-hoc), also determine doc_type, title, source_tool, and why_private from content or by asking the user. See references/ad-hoc-ingest.md.

Document Types

Two-Tier Taxonomy

The primary key is always the GitHub repo name. Within it, a second tier for sub-projects.

• Simple repo: {repo}/{repo}/ — repeat the name (e.g., ai-builder-kit/ai-knowledge-harvester/)
• Monorepo: {repo}/{sub-project}/ — one folder per sub-project (e.g., jack-dev-server-configs/generic-harness-v1/)

ai-knowledge/
├── README.md
├── projects/
│   ├── README.md
│   ├── {github-repo}/                    # Top tier: GitHub repo name
│   │   ├── README.md                     # Repo overview, why private, sub-project list
│   │   └── {sub-project}/               # Second tier: sub-project (or repo name repeated)
│   │       ├── README.md                 # Sub-project overview, type folder list
│   │       ├── specs/
│   │       │   ├── README.md
│   │       │   └── YYYY-MM-DD-{seq}-{slug}.md
│   │       ├── prompt-logs/
│   │       │   ├── README.md
│   │       │   └── YYYY-MM-DD-{seq}-{slug}.md
│   │       ├── working-docs/
│   │       │   ├── README.md
│   │       │   └── YYYY-MM-DD-{seq}-{slug}.md
│   │       └── harness-prompts/          # Optional — only if harness prompts exist
│   │           ├── README.md
│   │           └── YYYY-MM-DD-{seq}-{slug}.md
│   └── {another-repo}/
│       └── ...
└── shared/
    ├── README.md
    └── skills/

Each README describes its folder's purpose and lists immediate children only — never recurses deeper. For full README templates and frontmatter spec, see references/taxonomy.md.

Core Workflow

Mode 1: Repo Scan

1. Validate source_repo and knowledge_repo paths exist
2. Determine project name from GitHub remote, detect sub-projects (monorepo or simple)
3. Discover AI docs — scan ai-docs/, local-ai-docs/, local-only/, local/, nested subdirectories
4. Present classified list to user, wait for confirmation
5. Create project folder structure, write files with frontmatter
6. Create/update README.md files at each level (1 level deep)
7. Stage and commit changes — never push
8. Source files stay in place — only offer cleanup if the user explicitly asks

For detailed steps, scan patterns, and exclusion rules: see references/repo-scan.md.

Mode 2: Ad-Hoc Ingest

1. Read pasted content — detect source tool, classify type, identify project + sub-project
2. Ask the user if project, sub-project, type, or title is ambiguous — don't guess
3. Clean up formatting, prepend frontmatter with source_tool field
4. Write to correct type folder, update READMEs, stage and commit — never push

For detailed steps, source detection hints, and example interactions: see references/ad-hoc-ingest.md.

Edge Cases

Safety Rules

• Never push. Stage and commit, but never push to remote.
• Never modify source files during harvest. Read-only access to source repos during harvest.
• Never delete source files unless explicitly asked. Harvest is a copy, not a move. Source files stay in place by default.
• Never silently overwrite. Report every file action, especially collision resolutions (log both versions' dates and sizes).
• Ask when uncertain. Project, type, and title must be confirmed when ambiguous.

Why This Skill Exists

For the design rationale — why GitHub+markdown over Notion/CosmosDB, why project-first taxonomy, the open source philosophy, and what comes next — see references/spirit.md.