AgentSkel：为AI编程代理构建持久化记忆与团队共享标准的开源框架

AgentSkel is an innovative open-source framework designed to solve the 'session amnesia' problem of AI programming agents. By storing memory files via Git branches, standardizing workflows, and establishing a cross-tool compatible rule system, AgentSkel allows every AI agent in a team to share project knowledge, follow unified standards, and maintain context continuity across multiple sessions. It addresses the fundamental limitation of AI programming assistants (like Claude Code, GitHub Copilot, Cursor) — session statelessness — which leads to repeated work, inconsistent behaviors, and lack of shared architectural understanding in team environments.

AI programming assistants are revolutionizing software development but suffer from session statelessness: each new session requires re-scanning codebases, forgetting prior conventions, repeating errors, and ignoring past architectural decisions. In team settings, this worsens: agents behave inconsistently, propose conflicting solutions, and lack unified understanding of shared architectures (e.g., iOS/Android agents diverging on business logic).

Without AgentSkel, common issues include:

问题	具体表现
会话失忆	代理每次会话重新扫描40个文件，反复询问已回答过的问题
代码库规模限制	大型代码库超出上下文窗口，代理只能猜测
缺乏机构知识	代理不了解边界情况、设计决策背后的原因
标准漂移	五个开发者+五个AI工具=五种不同的代理行为
跨平台分歧	iOS和Android代理在共享业务逻辑上悄然产生分歧
重复犯错	没有代理能从上周的错误中吸取教训

AgentSkel solves these issues via three core mechanisms:

1. Persistent Knowledge Base: Uses Git isolated branch (ai-memory) as .memory/ worktree to store project knowledge in pure Markdown files.
2. Always-Enforced Rules: Hard principles like pre-coding planning, pre-release validation, and non-negotiable security.
3. Structured Workflows: 17 standardized processes covering feature development, bug fixes, code reviews, etc.

Key architectural design:

• Isolated Branch Worktree: Main branch holds app code, ai-memory branch stores memory files (mounted to .memory/), ensuring version control, non-intrusiveness, no vendor lock-in, and cross-tool compatibility.
• Memory File System: Includes MAP.md (code structure), SYMBOLS.md (class/function index), RESUME.md (session state), RULES.md (core rules), CONVENTIONS.md (coding styles), etc.

Structured workflows include:

• Core: Feature development (plan → branch → TDD → PR), bug fix (reproduce → test → root cause → fix), brainstorming.
• QA: Code review, test engineering, tech debt repair.
• Ops: Release, hotfix, dependency check.
• Knowledge: Codebase mapping, subagent dispatch, navigation.

AgentSkel supports multiple AI tools:

工具	集成方式
Claude Code	插件 + session-start钩子
Cursor	插件 + 原生规则
GitHub Copilot	.github/copilot-instructions.md
Windsurf	原生规则
Codex CLI	原生读取AGENTS.md
Gemini / Antigravity	扩展 + GEMINI.md

Compared to system prompts:

特性	系统提示	AgentSkel
共享性	个人级别	团队级别，通过Git共享
持久性	会话重置	永久存储在Git中
跨工具	不兼容	所有工具读取相同文件
知识积累	线性	复合增长，错误不再重复
架构决策传播	手动通知	自动同步

Installation:

• Claude Code: /plugin install agentskel
• Gemini CLI: gemini extensions install https://github.com/ahmadulhoq/agentskel
• Manual: git clone https://github.com/ahmadulhoq/agentskel.git → ./scripts/install-agent.sh

Project Initialization: Open project directory and say: "在这个项目上设置agentskel。" The agent creates memory files, copies rules/workflows, and opens a PR. After merging, say "映射这个代码库" to build the shared knowledge base.

Version Management: Agents detect version gaps at session start. Use: "将此项目与最新skeleton同步。" to apply updates and open PRs.

Implications:

• From personal tool to team infrastructure.
• From session memory to institutional knowledge.
• From tool lock-in to open standards.
• From linear improvement to compound growth.

Limitations:

1. Learning curve for team adoption of conventions.
2. Maintenance cost for updating memory files.
3. Partial tool support for specific features.
4. Need for Git advanced feature familiarity.

AgentSkel provides an elegant solution to AI programming agents' amnesia problem. It uses Git branches for persistent memory, standardized workflows for team consistency, and cross-tool compatibility to avoid vendor lock-in. As AI-assisted programming becomes widespread, AgentSkel will be a critical component for scaling AI collaboration in teams, turning individual efficiency tools into shared infrastructure.