Skip to main content

How to build a maintainable AI Skill β€” one that survives past 3 months

Skill workflow diagram β€” Input (raw sources) β†’ Processing (wiki) β†’ Output (outputs) with 9 operations: Ingest, Query, Lint, Compile, Categorize, Answer, File-back, Impute, Connect
Full workflow diagram β€” 9 operations across 3 zones: Input Β· Processing Β· Output. Lock icons πŸ”’ = operations that need your approval before running.

TL;DR: Most AI knowledge bases die within 2-3 months because nobody maintains the links between pages. If you want your Skill to still work after 6 months β€” not just be a dead markdown folder β€” you need three loops: Ingest β†’ Query β†’ Lint. This is the exact model I use for the 241-page Skill on this site. Original inspiration: how Karpathy uses Claude + Obsidian.

Why Skills die​

Week 1 you ingest 50 pages. Feels great. Next week you add 10 more. A month later, 5 more. Then you drop it.

Six months later you open it back up: 3 pages contradict each other, 7 pages are orphaned (nothing links to them), 2 pages describe the same thing under different slugs. AI reads it β†’ gets confused β†’ generates inconsistent proposals.

It's not that you're lazy. The root problem: the value of a Skill is in the links between pages, not in the number of pages. And links grow quadratically: 10 pages have 45 potential link pairs, 500 pages have 124,000+. A human can't hold that in their head. AI has to hold it for you.

The core principle​

Obsidian is the IDE, the LLM is the programmer, the wiki is the codebase.

Which means you treat the knowledge base like code:

  • Clear schema (rules)
  • Versioning + logs
  • A "linter" that runs regularly to catch problems
  • Atomic commits (each ingest = one idea, one commit)

If you've written code for years, you know a codebase without tests and linting rots fast. Knowledge bases work the same way.

The three core loops​

1. Ingest β€” turn raw sources into atomic pages​

Every source (article, video, course, transcript) lands in /raw. AI reads it, extracts the ideas, and writes each one as its own atomic page in /wiki, automatically adding wikilinks to related existing pages.

Rules:

  • One page = one idea (atomic)
  • Every page has: title, one-sentence summary, content in your voice, source citation
  • If a new page links to 3+ existing pages β†’ tag it as a "hub"
  • Write to log.md: date, source, pages created
  • Move the source from /raw to /raw/processed so you don't ingest it twice

Common mistake: copy-pasting entire paragraphs from the source. AI reading them back gets nothing new β€” no value added. You have to reword in your voice and add a "why this matters" note.

2. Query β€” turn questions into new pages​

When you ask AI a question ("how do I write a timeline-first hook for SaaS?"), AI doesn't answer from scratch like ChatGPT β€” it searches /wiki first, cites the pages it used, then answers.

The key insight: output becomes input. A good answer β†’ file it back into the wiki as a new page β†’ next time AI finds it instantly.

Rules:

  • Always search the wiki before answering
  • Cite the pages you drew from (like academic footnotes)
  • If two pages contradict each other, call the contradiction out β€” don't silently pick one
  • If the answer is worth saving, ask whether to file it back

This is the biggest difference from vanilla RAG: RAG searches from scratch every time; here you compile knowledge once, use it many times.

3. Lint β€” periodic maintenance​

This is the step 90% of people skip β€” and it's why 90% of wikis die.

Run it every 2-4 weeks. AI scans the entire wiki and reports:

  • Contradictions β€” page A says X, page B says the opposite
  • Outdated pages β€” a claim has been superseded but the page never got updated
  • Orphans β€” pages nothing links to; probably forgotten or duplicated
  • Gaps β€” a topic is referenced across many pages but has no dedicated page yet
  • Duplicates β€” two pages saying the same thing, need merging

Important: report only, never auto-delete. You read the report and decide merge / delete / reword.

The minimal architecture (5 components)​

You need exactly 5 things. No more.

/raw          β†’ unprocessed sources
/wiki         β†’ processed atomic pages
index.md      β†’ catalog of every wiki page
log.md        β†’ time log (ingest / compile / lint)
CLAUDE.md     β†’ schema that runs the whole system

CLAUDE.md is the control file. It defines the operations (Ingest, Query, Lint, Categorize, Answer, File-back) β€” each operation is a block of rules AI reads whenever you trigger it.

Example CLAUDE.md fragment for Ingest:

INGEST β€” when I say "ingest this":
1. Read the source fully
2. Split into atomic pages
3. Each page: title, 1-sentence summary, content in my voice, source
4. Wikilinks to related pages
5. If 3+ links β†’ mark as hub
6. Add to index.md
7. Write to log.md
8. Move source to /raw/processed

The power of the schema: you don't have to repeat these 8 steps each time. Just say "ingest this" and AI knows exactly what to do.

The compounding loop β€” why this Skill gets stronger the more you use it​

  • Week 1: 10 pages, 45 potential link pairs
  • Month 1: 50 pages, ~1,225 pairs
  • Month 6: 250 pages, ~31,000 pairs
  • Year 1: 500 pages, ~124,000 pairs

Page count grows linearly. Link count grows quadratically. That's why by year two, your Skill starts answering questions you never planned for β€” because old pages have connected in ways you didn't design upfront.

But it only compounds if something maintains the links. A human can't hold that at 250+ pages. AI can.

How this applies to the Upwork Skill​

My 241-page Skill was built with this exact model:

  • /raw: 103 sent proposals + coaching transcripts + copywriting course notes
  • /wiki: 241 atomic pages (blueprint, phrase, craft, rule, misstep, case study)
  • index.md: the 5-zone map you're viewing
  • log.md: log for every ingest + lint run
  • CLAUDE.md: schema defining 6 operations (Ingest, Query, Lint, Categorize, Answer, File-back, Compile)

Result: once you install the Skill into ChatGPT/Claude/Cursor, your AI doesn't just read 241 pages β€” it understands the relationships between them. Ask "which hook fits a b2b SaaS on a low budget?" and AI stitches together [blueprint-fast-delivery] + [shelf-hook-timeline] + [shelf-stack-saas] + [craft-pricing-by-vertical] into a recommendation β€” instead of reading pages in isolation.

If you want to build a Skill for your own niche (not Upwork), copy the same 5 components, write your own CLAUDE.md, and run the three loops Ingest β†’ Query β†’ Lint on a regular cadence.

Startup checklist for your own Skill​

  • Create 5 files: /raw, /wiki, index.md, log.md, CLAUDE.md
  • Write CLAUDE.md with 3 minimum operations: Ingest, Query, Lint
  • Ingest 5-10 first sources (your articles, videos, transcripts)
  • Run Query to test β€” ask 3 questions and check whether AI cites real pages
  • Schedule Lint every 2 weeks (Google Calendar, don't forget)
  • At 30 pages, run Categorize to build your first hub
  • At 100 pages, run Compile to rebuild the full index

Inspiration & references​

X

Graph View