akm-cli 0.9.29 → 0.9.31

package/docs/posts/team-skills-07.md

@@ -0,0 +1,198 @@
+---
+title: Your Team's Agent Skills Are a Mess. Here's How to Fix It.
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-skills
+description: Every agent skills article is about individual developers. But teams are where skills become valuable and messy simultaneously.
+tags:
+  - ai
+  - agents
+  - cli
+  - skills
+published: true
+id: 3426246
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+This is part seven in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. [Part one](https://dev.to/itlackey/your-ai-agents-skill-list-is-getting-out-of-hand-32ck) introduced progressive disclosure. [Part two](https://dev.to/itlackey/you-already-have-dozens-of-agent-skills-you-just-cant-find-them-bpo) unified your local assets across platforms. [Part three](https://dev.to/itlackey/your-agents-memory-shouldnt-disappear-when-the-session-ends) added remote context via OpenViking. *(note: OpenViking is not supported in akm v1 — see Part three's deprecation notice for details)* [Part four](https://dev.to/itlackey/your-agent-doesnt-know-what-the-community-already-figured-out) connected community knowledge through Context Hub.
+
+Everything up to now has been about *you*. Your skills. Your stash. Your agent. That's fine when you're working solo, but most of us aren't.
+
+You've got a deploy skill. Your teammate has one too. They do slightly different things — yours includes the canary step, theirs adds a Slack notification you didn't know about. A third person on the team wrote theirs for Codex and it skips the canary entirely.
+
+Now the deploy process changes. Say the team adds a new staging environment. You update your skill. You mention it in standup. Your teammate says they'll update theirs later. The third person was out that day and doesn't hear about it. Two weeks later, someone deploys to the wrong environment because their skill still has the old configuration.
+
+This isn't hypothetical. If your team uses AI coding assistants, this is happening right now. Every developer building up their own skill collection, no shared source of truth, no way to know when someone else has a better version of the same thing.
+
+Every agent skills article on the internet is written for individual developers. But teams are where skills become both most valuable and most chaotic. Here's how to fix it.
+
+## The Simplest Thing: A Shared Directory
+
+Your team already has a shared drive or mounted directory? Use it.
+
+```sh
+# Team lead creates the shared source
+mkdir -p /mnt/shared/team-skills/skills/deploy
+cat > /mnt/shared/team-skills/skills/deploy/SKILL.md << 'EOF'
+# Deploy to Production
+
+Standard deployment workflow for all services.
+
+## Steps
+1. Run test suite: `bun test`
+2. Build: `bun run build`
+3. Deploy to staging: `./scripts/deploy.sh staging`
+4. Run smoke tests: `./scripts/smoke.sh staging`
+5. Deploy to production: `./scripts/deploy.sh production`
+6. Notify #deploys channel in Slack
+
+## Rollback
+If smoke tests fail: `./scripts/rollback.sh staging`
+EOF
+```
+
+Each developer adds it as a source:
+
+```sh
+akm add /mnt/shared/team-skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm search "deploy"
+```
+
+That's it. The shared skill shows up in everyone's search results alongside their personal skills. When the team lead updates the deploy skill, everyone sees the update on the next index refresh. No copying. No syncing. No "hey, I updated the deploy skill" messages in Slack.
+
+This works best for co-located teams or teams that already share infrastructure. Zero overhead to set up.
+
+## Git for Distributed Teams
+
+If your team is distributed, a Git repo is the natural choice. You already use Git for everything else — why not for skills?
+
+```sh
+# Team lead creates the repo
+# github.com/your-org/team-agent-skills
+# Standard stash structure: skills/, commands/, knowledge/
+
+# Each developer adds it
+akm add github:your-org/team-agent-skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Pull latest when needed
+akm update --all  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+This buys you everything Git already provides:
+
+- **Version history.** See when the deploy skill changed and why.
+- **Pull request review.** New skills and updates go through the same review process as code.
+- **Branch-based testing.** Try a new version of a skill on a branch before merging.
+- **CI integration.** Lint your skill files, validate structure, run tests.
+
+A new developer runs `akm add`, and they've got the entire team's skill library indexed and searchable immediately. No onboarding doc that says "copy these files to these directories."
+
+## Private Registry for Larger Orgs
+
+For larger teams or organizations that want discoverability without mandating specific skills, `akm` supports private registries. Think npm for agent skills, but hosted internally.
+
+```sh
+# Configure the team registry once (applies to all subsequent searches)
+akm registry add https://registry.internal.company.com --name team
+
+# Search — registries you've added are searched automatically
+akm search "deploy" --from registry
+
+# Install a specific skill from the registry (each hit's `action` field
+# prints the exact `akm add <installRef>` to run)
+akm add https://registry.internal.company.com/skills/deploy-to-k8s  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+This makes more sense when your organization has dozens of teams, each with their own skills, and you want cross-team discovery without requiring everyone to index everything. Also handy when you need access control — some skills are sensitive.
+
+## When the Team Skill Doesn't Quite Fit
+
+Here's the scenario every team hits: the standard deploy skill works for 90% of cases. But your project has a specific environment variable, an extra pre-deploy step, or a different notification channel.
+
+You don't want to modify the team skill — that breaks it for everyone else. You don't want to write your own from scratch — that's the duplication problem we started with.
+
+`akm clone` solves this:
+
+```sh
+# Fork the team skill into your personal source
+akm clone skill:deploy
+
+# Now you have a local copy to customize
+# Edit ~/.akm/sources/default/skills/deploy/SKILL.md
+# Add your project-specific steps
+```
+
+The team version stays clean. Your fork is yours to customize. Both appear in your search results — the team version and your customized version — with the local fork ranked higher since it's in your personal source.
+
+When the team updates their version, you can re-clone to get the update and reapply your customizations. Or diff the two versions to see what changed.
+
+## Putting It Together
+
+Here's what the full workflow looks like for a team of five:
+
+**Team lead (one-time setup):**
+```sh
+# Create the team skills repo
+mkdir team-agent-skills
+cd team-agent-skills
+akm setup
+# Add skills, commands, knowledge
+# Push to github.com/your-org/team-agent-skills
+```
+
+**Each developer (one-time setup):**
+```sh
+# Add team source alongside personal sources
+akm add github:your-org/team-agent-skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add ~/.claude/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add ~/.codex/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+**Daily workflow:**
+```sh
+# Search finds results from all sources
+akm search "deploy"
+
+# Team skill and personal skills appear together
+# Best match wins, regardless of source
+
+# Pull team updates
+akm update --all  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+**When customization is needed:**
+```sh
+akm clone skill:deploy
+# Edit local copy
+# Both versions stay searchable
+```
+
+No file copying. No sync scripts. No "which version is correct?" conversations. The team source is the source of truth. Personal forks are explicitly personal. Search finds everything.
+
+## Why This Scales
+
+This whole workflow is built on the progressive disclosure pattern from the [previous post](https://dev.to/itlackey). At team scale, it's not just an optimization — it's a necessity.
+
+A team of five, each with 30 personal skills plus 50 shared team skills, has 200 total skills in play. Front-loading all of them into every agent session would cost 200,000+ tokens. With `akm`'s search-then-load pattern, each session uses only the 2-5 skills it actually needs.
+
+The agent doesn't know or care whether a skill came from the team source, a personal directory, or a Git repository. It searches, it finds, it loads. The source management is your concern as a developer. The skill content is the agent's concern. Clean separation.
+
+## Getting Started
+
+If you're a team lead looking to set up shared skills:
+
+1. Pick your approach — shared filesystem for co-located teams, Git repo for distributed teams, registry for large organizations
+2. Create the shared source — see the [Getting Started guide](../guides/getting-started.md) for the standard stash structure
+3. Have each developer run `akm add` to register the source
+4. Start with 3-5 high-value skills that everyone uses (deploy, test, review, etc.)
+5. Iterate from there
+
+The infrastructure is minimal. The payoff is immediate.
+
+Give it a shot and let me know how it holds up. The repo's at [github.com/itlackey/akm](https://github.com/itlackey/akm), and the [Getting Started guide](../guides/getting-started.md) will get you wired up in a few minutes.
+
+
+---
+
+> **Note (2026-04-23):** This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a *kit* and the *Kit Maker's Guide*; those terms have been renamed to *stash* and *Stash Maker's Guide* throughout. The pre-rename text is preserved in this repository's git history.

package/docs/posts/wiki-agent-knowledge-08.md

@@ -0,0 +1,223 @@
+---
+title: Building Agent Knowledge Bases That Actually Scale
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: 'akm multi-wiki support gives agents a searchable, maintainable knowledge base.'
+tags:
+  - ai
+  - agents
+  - cli
+  - knowledge
+published: true
+id: 3538936
+date: '2026-05-05T02:19:53Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+This is part eight in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. [Part one](https://dev.to/itlackey/your-ai-agents-skill-list-is-getting-out-of-hand-32ck) introduced progressive disclosure. [Part two](https://dev.to/itlackey/you-already-have-dozens-of-agent-skills-you-just-cant-find-them-bpo) unified your local assets across platforms. [Part three](https://dev.to/itlackey/your-agents-memory-shouldnt-disappear-when-the-session-ends) added persistent memory. Previous parts addressed teams, distributed stashes, and community knowledge.
+
+This one is about a different problem: knowledge accumulation.
+
+You start a new research area — say, LLM inference optimization. You read papers. You take notes. You save PDFs. Your agent writes summaries, discovers connections, asks follow-up questions that lead to more notes. Six weeks later you have a pile of markdown files, half-digested papers in a downloads folder, and a memory that says "we covered KV cache quantization somewhere." You search for it. You get three files with different partial takes on the same topic. None of them have the answer you need.
+
+This isn't a storage problem. You have all the information. It's a structural problem — and that's what akm's multi-wiki support is built to fix.
+
+## Karpathy's LLM Wiki Pattern
+
+In a GitHub gist, Andrej Karpathy described a pattern for maintaining a markdown knowledge base that a human and LLM build and maintain together. The core idea is deceptively simple: a structured directory of markdown pages, with an agent responsible for synthesizing incoming information into those pages over time.
+
+The insight is that agents are genuinely good at certain things that humans find tedious. Summarizing a 40-page paper into a two-paragraph page entry. Finding the connection between a new paper and something already in the knowledge base. Keeping a log of what was added and why. Updating an existing page when new information contradicts or extends it.
+
+What agents are not good at: maintaining invariants. An agent won't reliably enforce slug uniqueness. It won't regenerate an index consistently. It will sometimes overwrite a source file you meant to keep immutable. It loses track of what's been ingested when sessions end.
+
+So you need a division of labor. The agent does the synthesis. The tooling enforces the invariants. That's the gap akm's wiki support fills.
+
+## The Problem: Knowledge That Accumulates and Gets Lost
+
+Most developers hit this in one of two ways.
+
+The first way: you import a file as a knowledge asset (`akm import ./paper.md`) and your agent reads it directly. That works fine for one or two documents. At ten documents, the agent is loading full text into every relevant session. At thirty documents, you're spending tokens on context you don't need, and the agent is trying to mentally synthesize relationships across thirty separate files per session. Nothing is connected. Nothing is indexed.
+
+The second way: you ask your agent to "take notes" in a notes.md file. The file grows. It becomes a wall of text with no structure. Searching it is grep. Updating it means the agent has to read the whole thing before writing anything. After a few sessions the agent starts ignoring sections it wrote two weeks ago because they're below the fold.
+
+Both patterns fail in the same way: there's no structural home for the knowledge. No schema that says what a page is. No index that makes things findable. No log that tracks what happened. No separation between raw sources and synthesized pages.
+
+## How akm's Multi-Wiki Works
+
+A wiki in akm is a named subdirectory under `~/akm/wikis/`. Each wiki has a fixed structure:
+
+```
+~/akm/wikis/
+  research/
+    schema.md       # per-wiki rulebook: page kinds, voice, contradiction policy
+    index.md        # catalog of all pages — regenerated by akm index
+    log.md          # append-only activity log
+    raw/            # immutable ingested sources (never edit these)
+    attention.md    # a synthesized page
+    transformers/
+      architecture.md
+```
+
+You create a wiki with one command:
+
+```sh
+akm wiki create research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+```
+
+That scaffolds the directory, stubs out `schema.md` with sensible defaults, creates empty `index.md` and `log.md`, and makes the `raw/` directory. You're not starting from a blank directory — you're starting from a structural contract.
+
+The `schema.md` file is important. It's where you define the rules for this particular wiki: what page kinds are allowed, what the voice should be, how contradictions are handled, what the minimum viable page looks like. You edit it once when you create the wiki, and the agent reads it at the start of every ingest session. It's the wiki's constitution.
+
+## Walking Through a Real Workflow
+
+Say you're building a research wiki on transformer architectures. You have a paper PDF, some notes from a talk, and a few bookmarked articles.
+
+Start by bringing in the raw sources:
+
+```sh
+akm wiki stash research ./attention-paper.pdf --as attention  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+akm wiki stash research ./transformer-scaling-notes.md --as scaling-notes  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+echo "# Key quote from Sutton talk" | akm wiki stash research -  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+```
+
+The `stash` command copies each source into `raw/` with a unique slug. If you try to stash the same slug twice, it errors rather than overwriting. That's one of those invariants the agent can't reliably maintain — akm handles it.
+
+Now ask your agent to start the ingest workflow:
+
+```sh
+akm wiki ingest research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+```
+
+This dispatches the configured agent (from `config.defaults.agent` or `--profile`) with the wiki's ingest workflow as its prompt. The workflow tells the agent to: read `schema.md` to understand the page structure, check `index.md` to see what pages already exist, read each unprocessed file in `raw/`, synthesize content into pages using Write or Edit, update `index.md`, append a summary to `log.md`. `akm` owns the schema-aware commands (stash, search, lint, index, show); the agent owns the reasoning.
+
+After the agent runs the ingest workflow:
+
+```sh
+akm wiki pages research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+# → research/attention.md   "Self-attention mechanism and complexity analysis"
+# → research/transformers/architecture.md   "Encoder-decoder structure, residual connections"
+```
+
+Later, when you want to check the health of the wiki:
+
+```sh
+akm wiki lint research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+```
+
+Lint runs deterministic structural checks: orphan pages (not in index.md), broken xrefs in frontmatter, missing descriptions, raw files that appear uncited in any page, and whether the index is stale relative to the directory contents. These are checks that require counting and comparing file state — exactly the kind of thing agents do inconsistently.
+
+## The "akm Surfaces, the Agent Writes" Principle
+
+This division of labor is worth making explicit, because it determines what belongs in akm and what doesn't.
+
+akm handles operations that require invariants an agent can't reliably enforce across sessions:
+
+- Scaffolding (ensures required files exist with the right names)
+- Source import (unique slugs, never overwrites, immutable raw/)
+- Lint (deterministic structural checks against file system state)
+- Index regeneration (consistent format, triggered by normal indexing)
+- Workflow printing (a recipe the agent can follow without reinventing it)
+
+The agent handles everything that requires judgment:
+
+- Writing and updating pages
+- Synthesizing connections between sources
+- Deciding what a page should say and how to structure it
+- Appending meaningful log entries
+- Adding xrefs in frontmatter
+
+The reason this split matters: agents are good at synthesis and bad at reliability. If you ask an agent to "update the index," it will sometimes do it correctly, sometimes produce a subtly wrong format, and sometimes forget. If you ask it to write a page on attention mechanisms from three source documents, it will do that well every time. The tool enforces the boring, brittle parts so the agent can focus on what it's actually good at.
+
+There are no unconditional LLM calls inside akm for wiki operations. The wiki commands are pure file operations, SQLite, and structural analysis — fast, deterministic, and usable offline. (akm does ship bounded opt-in LLM calls for other workflows, like `akm improve` and `akm curate`, gated behind per-process toggles under `profiles.improve.<name>.processes.*` and the first-class `index.*` / `search.*` feature sections — all off by default. But the wiki tooling itself never touches an LLM.)
+
+## akm wiki search vs akm search --type wiki
+
+Once you have a few wikis, you'll use two different search paths depending on what you need.
+
+`akm wiki search research "attention mechanism"` runs a scoped search within the `research` wiki only. Use this when you know which wiki holds the answer and you want precision — no noise from other wikis or other asset types. The results are page refs with descriptions, scoped to `research/`. Raw sources under `raw/` plus the wiki root infrastructure files `schema.md`, `index.md`, and `log.md` are excluded from the search index and never appear as search hits.
+
+`akm search --type wiki "attention mechanism"` runs the full stash-wide search across all wiki pages. Use this when you're not sure which wiki something lives in, or when you want to see if anything from multiple wikis is relevant to a task before loading anything.
+
+In practice: scoped search during active work in a specific domain, wide search when starting a new session or doing cross-domain research. Wiki pages participate in the same FTS5 scoring pipeline as every other asset type, so `--type wiki` is not a second-class citizen — a highly relevant wiki page will outrank a mediocre skill in a general search.
+
+## Practical Example: Building a Research Wiki
+
+Here's the complete workflow for setting up and using a research wiki from scratch.
+
+**Initial setup:**
+
+```sh
+akm wiki create research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+# Edit wikis/research/schema.md to define your page kinds
+# (technical-summary, comparison, open-question, etc.)
+```
+
+**Bring in sources as you find them:**
+
+```sh
+akm wiki stash research ./papers/attention-is-all-you-need.pdf --as attention-2017  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+akm wiki stash research ./papers/flash-attention-v2.pdf --as flash-attention-v2  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+akm wiki stash research ./notes/scaling-laws-talk.md --as scaling-laws-notes  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+```
+
+**Run ingest when you're ready to synthesize:**
+
+```sh
+akm wiki ingest research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+# Agent reads the recipe, reads raw/ files, writes pages, updates index, logs activity
+```
+
+**Check what exists:**
+
+```sh
+akm wiki pages research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+akm wiki show research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+```
+
+**Search when working on a related task:**
+
+```sh
+akm wiki search research "KV cache memory"  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+# Returns: research/attention.md, research/flash-attention/optimization.md
+```
+
+**Lint before a long agent session to catch structural drift:**
+
+```sh
+akm wiki lint research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+# Orphans: none
+# Broken xrefs: research/flash-attention/optimization.md → research/kv-cache.md (missing)
+# Stale index: yes (run akm index)
+```
+
+**Fix the stale index:**
+
+```sh
+akm index
+# Rebuilds SQLite search index, regenerates wikis/research/index.md as a side effect
+```
+
+At the end of a few weeks, you have a structured, searchable knowledge base. Your agent can load specific pages by ref instead of reading all thirty raw sources every session. You can run lint any time to catch drift. The log tells you what was synthesized and when. The raw sources are still there if you ever need to re-derive something from primary material.
+
+## What This Isn't
+
+Multi-wiki is not a document management system. If you want to store and retrieve original documents, `akm import` and the `knowledge` type already do that.
+
+It's not a notes app. Single notes go in memories. Reference material goes in knowledge. Wikis are specifically for synthesized, structured knowledge that grows over time through an active ingest process.
+
+As of 0.8.0, `akm wiki ingest <name>` dispatches the configured agent (`defaults.agent` or `--profile`) to execute the ingest workflow end-to-end. The agent reads the schema, finds related pages, creates new pages, updates xrefs, appends to `log.md`, and reindexes — all through `akm`'s schema-aware commands. The wiki tooling owns the invariants; the agent owns the reasoning.
+
+## Getting Started
+
+Multi-wiki has been available since akm 0.5.0. If you're already using akm, upgrade and try:
+
+```sh
+akm wiki create research  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+akm wiki list  # doclint:ignore (historical — akm multi-wiki era post; `wiki` family removed in 0.9.0)
+```
+
+The [Getting Started guide](../guides/getting-started.md) covers initial setup if you're new to akm. The wiki commands are available immediately once you have a stash configured.
+
+If you're working in a domain where knowledge accumulates — research, security analysis, architecture decisions, competitive analysis — give it a run and see if the structure helps. The repo is at [github.com/itlackey/akm](https://github.com/itlackey/akm). Questions and feedback in the issues.