[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1570":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":15,"starSnapshotCount":15,"syncStatus":35,"lastSyncTime":36,"discoverSource":37},1570,"skill-based-architecture","WoJiSama\u002Fskill-based-architecture","WoJiSama","A meta-skill that produces skills. Point it at any codebase and it distills the project's rules, workflows, and hard-won lessons into a dedicated skills\u002F\u003Cname>\u002F directory — a project skill that becomes the single source of truth every AI agent (Cursor, Claude Code, Codex, Windsurf, Gemini) consults before every task.","",null,"Shell",300,29,1,0,9,30,103,27,4.43,"MIT License",false,"main",true,[26,27,28,29,30,31],"agent","ai","chatbot","claude","markdown","skill","2026-06-12 02:00:29","# Skill-Based Architecture\n\n\u003Cp align=\"left\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FWoJiSama\u002Fskill-based-architecture\u002Fstargazers\">\n    \u003Cimg alt=\"GitHub stars\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FWoJiSama\u002Fskill-based-architecture?style=flat&logo=github\">\n  \u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\n    \u003Cimg alt=\"License\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002FWoJiSama\u002Fskill-based-architecture?style=flat\">\n  \u003C\u002Fa>\n  \u003Cimg alt=\"Status\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-alpha-orange\">\n  \u003Cimg alt=\"Commit activity\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcommit-activity\u002Fm\u002FWoJiSama\u002Fskill-based-architecture?style=flat\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FWoJiSama\u002Fskill-based-architecture\u002Fcommits\">\n    \u003Cimg alt=\"Last commit\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flast-commit\u002FWoJiSama\u002Fskill-based-architecture?style=flat&logo=github\">\n  \u003C\u002Fa>\n  \u003Cimg alt=\"Skill-Based Architecture\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSkill--Based-Architecture-blue\">\n\u003C\u002Fp>\n\n**English** | [中文](README.zh-CN.md)\n\n> A **meta-skill for turning scattered AI-agent rules into a maintainable project skill.** It audits rule sources such as `AGENTS.md`, `CLAUDE.md`, `.cursor\u002Frules\u002F`, README notes, and local workflow docs, then consolidates durable rules, repeatable workflows, and costly gotchas under `skills\u002F\u003Cname>\u002F`.\n\n**The output is a project rule system, not another README.** `SKILL.md` routes the task; `rules\u002F` holds stable constraints; `workflows\u002F` holds procedures; `references\u002F` holds architecture notes and gotchas. Tool-specific entry files stay as thin compatibility shells that point agents to the right task path without duplicating rule bodies.\n\n```\nscattered project guidance\nAGENTS.md \u002F CLAUDE.md \u002F .cursor\u002Frules \u002F README notes\n        │\n        ▼\nskill-based-architecture  (meta-skill)\n        │\n        ▼\nskills\u002F\u003Cproject>\u002F\n├── SKILL.md          # router: Always Read + Common Tasks\n├── rules\u002F            # stable constraints\n├── workflows\u002F        # repeatable procedures\n├── references\u002F       # architecture, gotchas, indexes\n└── docs\u002F             # optional reports and prompts\n\ntool entry files\nAGENTS.md \u002F CLAUDE.md \u002F CODEX.md \u002F GEMINI.md \u002F .cursor\u002Frules \u002F .codex\n        └── thin shells: route to skills\u002F\u003Cproject>\u002F, no duplicated rule bodies\n```\n\n## Why This Exists\n\nAI coding agents (Cursor, Claude Code, Codex, Windsurf, OpenCode, etc.) rely on project documentation to understand rules, conventions, and workflows. But as projects grow, that documentation inevitably becomes a mess:\n\n| Symptom | What Actually Happens |\n|---------|----------------------|\n| Single SKILL.md with 400+ lines | Agent reads **everything** on every task — wastes tokens, slows responses, hard to maintain |\n| Rules scattered across AGENTS.md, .cursor\u002Frules\u002F, CLAUDE.md | Duplicated content, contradictory rules, no single source of truth |\n| Rules only grow, never shrink | Useful rules get buried by obsolete ones; agents can't distinguish what matters |\n| Skill activation is unreliable | Description is a passive summary instead of explicit activation conditions |\n| Hard-won lessons buried in docs | Costly pitfalls (30+ min debugging) never surface during task execution |\n| Agent skips after-action review | Lessons discovered during work are lost; the same mistakes happen again |\n| Records are project-specific | Lessons written as narratives instead of reusable, transferable knowledge |\n\n**The result:** agents waste context reading irrelevant docs, miss critical rules, repeat known mistakes, and produce inconsistent output.\n\n## What This Solves\n\nSkill-Based Architecture provides a **structural pattern** for organizing AI agent documentation that:\n\n1. **Minimizes token waste** — agents read 2-3 core files per task instead of everything\n2. **Eliminates duplication** — one source of truth per rule, thin shells everywhere else\n3. **Routes by task** — a \"Common Tasks\" table directs agents to exactly the files they need\n4. **Captures lessons consistently** — built-in After-Action Review with recording thresholds\n5. **Self-maintains** — health checks, split\u002Fmerge procedures, and deprecation workflows keep docs lean\n6. **Works across harnesses** — compatible with Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, and AGENTS.md-based tools\n\n## Target Structure\n\n```\nskills\u002F\u003Cname>\u002F\n├── SKILL.md          # \u003C= 100 lines: always-read list + generated Common Tasks\n├── rules\u002F            # Long-lived constraints (what is always true)\n├── workflows\u002F        # Step-by-step procedures (how to do things)\n├── references\u002F       # Background: architecture, gotchas, indexes\n│   └── gotchas.md    # Known pitfalls — often the highest-value content\n└── docs\u002F             # Optional: prompts, reports, external docs\n```\n\nRoot entries (`AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `.cursor\u002Frules\u002F*.mdc`, `.codex\u002F`) become **thin shells** — compatibility entry points with inline routing and pointers to the formal skill, not duplicated rule bodies.\n\n---\n\n## Key Features\n\n### Two-Layer Routing\n\n`SKILL.md` keeps a short generated **Always Read** list for every task, then uses a generated **Common Tasks** summary to route the agent to extra files only when needed. In downstream projects, `routing.yaml` is the editable source of truth for Always Read files, Common Tasks, trigger examples, required reads, workflows, and thin-shell bootstraps.\n\n### Thin Shells with Routing Bootstrap\n\nEvery entry file (`AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `.codex\u002Finstructions.md`, `.cursor\u002Frules\u002F*.mdc`) embeds a short bootstrap that points to `routing.yaml` and explains how to match `labels` \u002F `trigger_examples`. The route data itself is not duplicated across shells.\n\n### Description as Trigger Condition\n\nThe `description` field decides whether the agent activates the skill. Keep it at the **domain \u002F intent-cluster** level, with real phrases users say, for example both `\"this endpoint is failing\"` and `\"这个接口报错了\"`. Do not list every workflow there — `SKILL.md` Common Tasks handles task-level routing after activation. `check-description-routing.sh` catches obvious over-broad descriptions and multi-skill trigger overlap.\n\n### Session Discipline\n\nEvery new task — even the second or third in the same session — must re-read SKILL.md, re-match the route in `routing.yaml`, and re-read all files listed for that route.\n\nThis avoids stale partial memory after `\u002Fcompact`, `\u002Fclear`, or a long multi-task session.\n\n### Task Closure and Freshness Checks\n\nNon-trivial tasks end with a short After-Action Review: verify the work, decide whether any repeatable\u002Fcostly\u002Fnon-obvious lesson should be recorded, and check whether any rule has gone stale. Doc edits also run description-routing, link, orphan-reference, cross-reference, and external-fact freshness checks.\n\n---\n\n## When NOT to Use This\n\nNot every project needs this architecture. Skip it if:\n\n- **Short-lived solo project (\u003C 2 weeks)** — no recurring tasks, no rules worth capturing\n- **Total rule content \u003C 50 lines** — a single `CLAUDE.md`, `AGENTS.md`, or `.cursor\u002Frules\u002Fworkflow.mdc` file is enough\n- **Single harness only** — you only use one AI tool and don't need cross-tool compatibility\n- **No team sharing** — you're the only person using AI agents on this codebase, and it's small enough to keep in your head\n\nIn these cases, start with a plain `CLAUDE.md` or `.cursor\u002Frules\u002Fworkflow.mdc`. You can always migrate to the full architecture later when the project grows — [WORKFLOW.md](WORKFLOW.md) has a Quick Start path for exactly that upgrade.\n\n---\n\n## Quick Start\n\n### Step 1 — Clone It Locally\n\nPick the location your agent can read. The flow is the same in every case: first make this meta-skill available locally, then trigger it from the target project.\n\n| Use case | Clone target |\n|---|---|\n| Cursor user-level skill | `~\u002F.cursor\u002Fskills\u002Fskill-based-architecture` |\n| Cursor project-level skill | `.cursor\u002Fskills\u002Fskill-based-architecture` |\n| Claude Code \u002F Codex \u002F Gemini \u002F Windsurf \u002F AGENTS.md-based agents | `skills\u002Fskill-based-architecture` inside the target project, or `..\u002Fskill-based-architecture` next to it |\n\n```bash\n# Cursor user-level install\ngit clone https:\u002F\u002Fgithub.com\u002FWoJiSama\u002Fskill-based-architecture.git \\\n  ~\u002F.cursor\u002Fskills\u002Fskill-based-architecture\n\n# Cursor project-level install\ngit clone https:\u002F\u002Fgithub.com\u002FWoJiSama\u002Fskill-based-architecture.git \\\n  .cursor\u002Fskills\u002Fskill-based-architecture\n\n# Generic project-local install\ngit clone https:\u002F\u002Fgithub.com\u002FWoJiSama\u002Fskill-based-architecture.git \\\n  skills\u002Fskill-based-architecture\n```\n\nIf your agent does not discover skills automatically, add a short pointer in `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, or the equivalent entry file:\n\n```md\nFor rule restructuring tasks, use the skill at `skills\u002Fskill-based-architecture\u002F`.\nRead `skills\u002Fskill-based-architecture\u002FSKILL.md` first.\n```\n\nIf you cloned the repo next to the target project instead, replace the path with `..\u002Fskill-based-architecture\u002FSKILL.md`.\n\n### Step 2 — Trigger It From the Target Project\n\nIn the target project, ask the agent to use the local meta-skill:\n\n> \"Use skill-based-architecture to refactor the project rules\"\n\nEquivalent trigger phrases also work:\n\n- \"Organize the project rules\"\n- \"Refactor the project rules into a skill-based architecture\"\n- \"Clean up scattered documentation\"\n- \"Consolidate rules into a skills directory\"\n- \"Migrate rules to skills\u002F\"\n\n### Scaffold a New Project\n\nAfter activation, the agent copies the pre-built scaffold from [`templates\u002F`](templates\u002F) into `skills\u002F\u003Cname>\u002F`, creates the thin shells, fills every `\u003C!-- FILL: -->` marker, and verifies the result. The exact command lives in [WORKFLOW.md Quick Start](WORKFLOW.md#quick-start-copy-dont-generate).\n\n### Pre-built Templates\n\n[`templates\u002F`](templates\u002F) is the copy source for skill files, thin shells, hooks, scripts, and protocol blocks. Copy these files instead of regenerating them inline. See [`templates\u002FREADME.md`](templates\u002FREADME.md) for the template map and [`templates\u002FANTI-TEMPLATES.md`](templates\u002FANTI-TEMPLATES.md) for content that intentionally stays out of reusable templates.\n\n---\n\n## What Happens After You Trigger It\n\nThe README only shows the operating shape. The detailed migration checklist lives in [WORKFLOW.md](WORKFLOW.md).\n\n1. **Audit current guidance** — find rule sources such as `AGENTS.md`, `CLAUDE.md`, `.cursor\u002Frules\u002F`, README notes, and existing docs.\n2. **Create the project skill** — copy the scaffold into `skills\u002F\u003Cname>\u002F`, then fill `SKILL.md`, `rules\u002F`, `workflows\u002F`, and `references\u002F` with project-specific evidence.\n3. **Wire entry files** — create thin shells for the tools you use, keeping rule bodies in `skills\u002F\u003Cname>\u002F`.\n4. **Validate** — run the copied scripts for structure, routing, placeholders, links, orphaned references, and external-fact freshness.\n\nUse the full [WORKFLOW.md](WORKFLOW.md) when you are actually performing a migration; keep the README as the short orientation page.\n\n---\n\n## Extending the Skill\n\nAfter the first migration, keep growing the project skill through routing instead of copying rule text into more places:\n\n- Add project-specific workflows such as `plan.md`, `review.md`, or `deploy-check.md`.\n- Let a workflow invoke another skill when that is the natural tool for the subtask.\n- Add reusable protocol blocks when the same discipline problem repeats.\n- Add one task to `routing.yaml` whenever a new recurring task appears, then run `scripts\u002Fsync-routing.sh`.\n- When this upstream project changes, tell the agent \"update from upstream\"; it should follow `workflows\u002Fupdate-upstream.md`, clone the GitHub source, patch locally, and preserve project-specific rules.\n\n---\n\n## Tool Compatibility\n\n\u003C!-- external-fact: verified=2026-04-28 source=https:\u002F\u002Fdocs.cursor.com\u002Fen\u002Fcontext -->\n\u003C!-- external-fact: verified=2026-04-28 source=https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fskills -->\n\u003C!-- external-fact: verified=2026-04-28 source=https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fguides\u002Fagents-md -->\n\u003C!-- external-fact: verified=2026-04-28 source=https:\u002F\u002Fdocs.windsurf.com\u002Fwindsurf\u002Fcascade\u002Fmemories -->\n\u003C!-- external-fact: verified=2026-04-28 source=https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli\u002Fblob\u002Fmain\u002Fdocs\u002Fcli\u002Fgemini-md.md -->\n\u003C!-- external-fact: verified=2026-04-28 source=https:\u002F\u002Fopencode.ai\u002Fdocs\u002Frules\u002F -->\n\n| Tool | Discovery Mechanism | Required Entry | Inline Routing? |\n|---|---|---|---|\n| **Cursor** | Uses project skill registration under `.cursor\u002Fskills\u002F` for this scaffold | `.cursor\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | Yes |\n| **Cursor rules** | `.cursor\u002Frules\u002F*.mdc` | `.cursor\u002Frules\u002Fworkflow.mdc` | Yes |\n| **Claude Code** | Reads root `CLAUDE.md`; native skills scan `.claude\u002Fskills\u002F` with enterprise > personal > project same-name precedence | `CLAUDE.md`; optional `.claude\u002Fskills\u002F\u003Cproject-name>\u002FSKILL.md` stub | Yes |\n| **Codex CLI** | Reads the `AGENTS.md` hierarchy; `AGENTS.override.md` can override project guidance | `AGENTS.md`; keep `CODEX.md` \u002F `.codex\u002Finstructions.md` only as compatibility mirrors if your harness reads them | Yes |\n| **Windsurf** | Reads workspace memories\u002Frules such as `.windsurf\u002Frules\u002F`; can also infer memories from `AGENTS.md` | `.windsurf\u002Frules\u002F*.md` or shared `AGENTS.md` shell | Yes |\n| **Gemini CLI** | Reads `GEMINI.md` at repo root (+ parent\u002Fchild dirs) | `GEMINI.md` | Yes |\n| **OpenCode** | Reads `AGENTS.md` | `AGENTS.md` shared shell | Yes |\n| **Other agents** | Reads `AGENTS.md` | `AGENTS.md` | Yes |\n\nAll entry files **must** contain a `routing.yaml` bootstrap — natural-language-only instructions get lost during context summarization, but duplicating the full route table in every shell creates drift pressure.\n\nFor Claude Code native skills, avoid generic project skill names that may collide with `~\u002F.claude\u002Fskills\u002F`: a personal skill with the same name overrides the project native skill. The project `skills\u002F\u003Cname>\u002F` directory remains the source of truth through `CLAUDE.md` and optional SessionStart routing.\n\n---\n\n## Files in This Repo\n\n| File | Content |\n|------|---------|\n| [SKILL.md](SKILL.md) | Skill entry: when to use, target structure, and core principles |\n| [WORKFLOW.md](WORKFLOW.md) | Migration guide: decision tree, quick-start scaffold, full 9-phase process, downstream upgrade |\n| [REFERENCE.md](REFERENCE.md) | Stub + index — redirects to [`references\u002F`](references\u002F) |\n| [references\u002F](references\u002F) | Layout, thin shells, protocols, conventions, multi-skill routing, skill composition, and self-hosting routing |\n| [TEMPLATES-GUIDE.md](TEMPLATES-GUIDE.md) | Annotated guide for template families and Task Closure Protocol |\n| [templates\u002F](templates\u002F) | Byte-for-byte scaffold files copied into downstream projects |\n| [EXAMPLES.md](EXAMPLES.md) | Stub + index — redirects to [`examples\u002F`](examples\u002F) |\n| [examples\u002F](examples\u002F) | Migration, project-type, self-evolution, and behavior-failure examples |\n| [skill.yaml](skill.yaml) | Machine-readable metadata for tool discovery |\n\n---\n\n## FAQ\n\n**Q: Does this replace the official Anthropic skill template?**\nNo. The official template defines the *minimal* skill shape (a folder with SKILL.md + frontmatter). This meta-skill starts one level later — it adds structure when a single small SKILL.md is no longer enough.\n\n**Q: When should I NOT use this?**\n- Very small projects (fewer than 3 rule\u002Fdoc files)\n- Temporary repos with no long-term maintenance needs\n- Teams with a well-functioning documentation system who don't want to migrate\n\n**Q: Can I migrate incrementally?**\nYes. Round 1: create `skills\u002F\u003Cname>\u002F` and extract rules. Round 2: extract workflows. Round 3: extract references and create thin shells. Each round leaves the project in a working state.\n\n**Q: What if my SKILL.md is still small?**\nKeep it as a single file using the minimal starter template. Upgrade only when content starts to sprawl, duplicate, or accumulate non-obvious lessons.\n\n**Q: How do I prevent documentation bloat?**\nThe recording threshold (2\u002F3: repeatable + costly + not obvious) filters out low-value records. The deprecation workflow in `update-rules.md` removes obsolete rules. `maintain-docs.md`, `check-description-routing.sh`, reference audits, cross-reference checks, and `check-external-facts.sh` catch oversized files, vague triggers, orphaned references, stale links, and stale external claims.\n\n**Q: How do downstream projects receive upstream improvements?**\nAsk the agent to update from upstream. The copied `workflows\u002Fupdate-upstream.md` contains the GitHub source URL and tells the agent to clone the latest upstream, compare files itself, patch useful mechanism changes, preserve project-owned rules\u002Fgotchas, then run validation.\n\n---\n\n## Community support\n\nLearn AI on LinuxDO — [LinuxDO](https:\u002F\u002Flinux.do\u002F)\n\n---\n\n## Star History\n\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F?repos=WoJiSama%2Fskill-based-architecture&type=date&legend=top-left\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=WoJiSama\u002Fskill-based-architecture&type=date&theme=dark&legend=top-left\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=WoJiSama\u002Fskill-based-architecture&type=date&legend=top-left\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=WoJiSama\u002Fskill-based-architecture&type=date&legend=top-left\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n","Skill-Based Architecture 项目旨在将分散在各处的AI代理规则整合成易于维护的项目技能。其核心功能是从诸如AGENTS.md、CLAUDE.md等文件中提取项目的规则、工作流和经验教训，并将其归类存储于一个专门的skills\u002F\u003Cname>\u002F目录下，形成单一事实来源。该架构通过SKILL.md作为任务路由器，rules\u002F存放稳定约束，workflows\u002F记录可重复流程，references\u002F保存架构笔记和注意事项，确保了信息的一致性和高效性。此工具特别适用于需要多AI代理协作且文档管理复杂的软件开发场景，帮助团队更好地组织和利用项目知识。",2,"2026-06-11 02:44:43","CREATED_QUERY"]