What it does
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/ / directory — a project skill that becomes the single source of truth every AI agent (Cursor, Claude Code, Codex, Windsurf, Gemini) consults befo…
- Connects Instruction files the AI reads
- Account or key Not confirmed yet (README not read yet)
- Category Coding
For makers: add a badge to your README
If you made this, paste this code into your README. The badge links back to this page.
[](https://mcp.popnx.com/en/skills/wojisama-skill-based-architecture)Use together with
MCP servers that connect the AI to services for the same work
Fallow
Codebase intelligence for TypeScript and JavaScript, exposed as structured MCP analysis tools.
Desktop Commander
MCP server for terminal commands, file operations, and process management
Similar Skills
Same kind of work, ordered like the Skills list
| This one skill-based-architecture | rea | andrej-karpathy-skills | graphify | MoneyPrinterTurbo | |
|---|---|---|---|---|---|
| Maker | WoJiSama | morluto | multica-ai | Graphify-Labs | harry0703 |
| Skills | 1 | 1 | 1 | 1 | 1 |
| GitHub stars | 625 | 465,460 | 233,910 | 149,364 | 144,149 |
| Last code change | Nov 13, 2026 | Nov 17, 2026 | Apr 20, 2026 | Nov 17, 2026 | Nov 17, 2026 |
| License | MIT | MIT | – | Apache-2.0 | MIT |
1 skills (instruction sets) by WoJiSama that an AI reads and follows · not an MCP server
How a Skill differs from MCP
MCP = the hands
Connects the AI to an outside service or data, such as reading Notion or creating an invoice. A program or server has to be running.
Skill = the manual
A text file that teaches the AI how to do a task. It connects to nothing.
Some overlap: a few Skills run scripts that call tools, and a few MCP servers only send knowledge. Start from the task you want done.
Works with
Claude CodeCodexCursorGemini CLIGitHub CopilotWindsurfOpenCode
From the maker’s README and the folders in the repo
Install
Is it safe?
- Who made it
GitHub account WoJiSama (person), 4 years old
- Use and upkeep
★ 625 stars · code last changed Nov 13, 2026
- Any scripts?
25 scripts that can run on a computer: .claude/hooks/session-start, scripts/check-all.sh, scripts/check-live-agent-journey.sh, scripts/check-self-scenarios.sh and 21 more
- Uses the internet?
Could not check every script (some are too large); read them first
- Changes machine-wide settings?
Installing the maker’s way adds hooks that run without you asking: run every time the AI edits a file · run every time a chat starts · Installed as a plugin (/plugin) it will run every time the AI edits a file in every project
Checked automatically from the repo files at commit 17612cb (read only, nothing was run). Not a safety guarantee: read it and decide for yourself
First: which AI do you use?
Pick your app and this page shows only how to install it there
Option 1Upload to claude.ai (web and app)
Uploading to claude.ai would fail: the description is over 200 characters (414). Use "Let the AI install it" instead
Option 1Let Claude Code install it
Copy this sentence and paste it into a Claude Code chat
For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing
The AI tells you what it will do first and asks your permission at every step
Restart Claude Code, then type /skill-based-architecture or ask for a matching task and Claude picks it up
Checked against official docs Nov 12, 2026 · Source: code.claude.com
For Terminal users
A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.
The maker’s recommended way
Checking the commands · copy buttons appear once they pass
Copied from the maker’s README; it downloads and runs the maker’s code
Open Terminal
Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead
Copy the skill folder to ~/.claude/skills
This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md
Checking the commands · copy buttons appear once they pass
Restart Claude Code, then type /skill-based-architecture or ask for a matching task and Claude picks it up
ChatGPT desktop app
The ChatGPT desktop app has Codex built in, and Codex reads skills from ~/.agents/skills
Option 1Let ChatGPT install it
Open Codex in the ChatGPT desktop app and paste this sentence into the chat
The AI always shows you the path before installing
The AI tells you what it will do first and asks your permission at every step
Option 2Put the folder there yourself
Put the skill-based-architecture folder at ~/.agents/skills/skill-based-architecture
~ is your home folder ($HOME)
For Terminal users
A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.
Open Terminal
Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead
Copy the skill folder to ~/.agents/skills
This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md
Checking the commands · copy buttons appear once they pass
After installing
- ChatGPT desktop app: open Skills in the sidebar to see that the skill is there
- To use it: in ChatGPT type @ and pick the skill · in Codex CLI or the IDE extension run /skills or type $ and the skill name
- Codex picks up newly installed skills by itself; if one does not show up, restart Codex
Checked against official docs Nov 15, 2026 · Source: learn.chatgpt.com
ChatGPT on the web and mobile
Skills you install yourself do not work here; only skills that come with a plugin from the directory
To use this skill with ChatGPT, use the ChatGPT desktop app as above
Checked against official docs Nov 15, 2026 · Source: learn.chatgpt.com
Option 1Let Codex install it
Copy this sentence and paste it into a Codex chat · Works in Codex inside the ChatGPT desktop app, Codex CLI and the IDE extension
For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing
The AI tells you what it will do first and asks your permission at every step
Codex picks up newly installed skills by itself; if one does not show up, restart Codex · To use it: in ChatGPT type @ and pick the skill · in Codex CLI or the IDE extension run /skills or type $ and the skill name
Checked against official docs Nov 15, 2026 · Source: learn.chatgpt.com
For Terminal users
A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.
Open Terminal
Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead
Copy the skill folder to ~/.agents/skills
This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md
Checking the commands · copy buttons appear once they pass
Restart Codex, then ask for a matching task; Codex lists the skill
Option 1Let Cursor install it
Copy this sentence and paste it into a Cursor chat
For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing
The AI tells you what it will do first and asks your permission at every step
In Cursor’s Agent chat, type / and pick skill-based-architecture
Checked against official docs Nov 12, 2026 · Source: cursor.com
For Terminal users
A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.
Open Terminal
Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead
Copy the skill folder to ~/.cursor/skills
This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md
Checking the commands · copy buttons appear once they pass
In Cursor’s Agent chat, type / and pick skill-based-architecture
Option 1Let the AI install it
For other apps that read skills. The sentence gives the paths for Claude Code, Codex and Cursor so the AI picks the one for your app · Copy this sentence into the app’s chat
For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing
The AI tells you what it will do first and asks your permission at every step
Checked against official docs Nov 12, 2026 · Source: code.claude.com, learn.chatgpt.com, cursor.com
For Terminal users
Other apps that support Agent Skills (such as Gemini CLI or GitHub Copilot) use different folders. Check that app’s guide, then copy the folder with the SKILL.md there.
Skill folders checked against the official Claude Code, Codex and Cursor guides on Nov 11, 2026
View the original SKILL.md
The text below comes from the maker’s repo, not from PopNx MCP
Showing the first 8,000 characters · Open the full file on GitHub
---
name: skill-based-architecture
description: >
This skill should be used when the user asks to "organize the project rules",
"clean up scattered documentation", "把规则迁移到 skills 目录", "优化 skill 路由",
"提高 description 命中率", or "减少薄壳重复维护".
Activate when a SKILL.md is too large, rules are duplicated across agent entry
files, task routing or trigger_examples miss natural user language, or
templates / thin shells / validation scripts need drift-resistant maintenance.
---
# Skill-Based Architecture
Restructure oversized single-file Skills or scattered project rules into a well-organized Skill directory. Builds on the official minimal Agent Skill contract (`name` + `description`) and kicks in when a single small `SKILL.md` is no longer enough.
## When to Use
- A single `SKILL.md` exceeds ~150 lines, mixing rules, workflows, and background material; or project rules are scattered across `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `.cursor/rules/`, `.claude/`, etc.
- Recurring tasks need procedures, fitted verification, or reliable completion checks; or the user explicitly requests Skill-based architecture or rule consolidation.
- Skip temporary repos with no durable routing need, teams with a working compact instruction system, and small projects; an explicit SBA request may still materialize a complete direct `SKILL.md` carrier.
## Progressive Rigor
Grow only under pressure. The materializer derives **Single-file**, **Folder-light**, or **Full/broad** internally from target evidence; users do not select a tier, profile, capability pack, or install mode. `routing.yaml`, Task Execution, Task Closure, maintenance checks, and each harness surface need their own routing/loading/ownership pressure. **Split by abstraction (骨架/肉)** when content tangles invariant design theory with current-code facts: abstract theory → `architecture/`, code maps → `references/`, house style → `conventions/`, per-module landmines → `gotchas/` (methodology stays in `rules/`). Downgrade when content shrinks. Details: [references/progressive-rigor.md](references/progressive-rigor.md).
## Evidence-Selected Structure
```text
# direct
skills/<name>/SKILL.md
# folder-light or broad: only admitted owners/directories
skills/<name>/{SKILL.md,rules/,workflows/,references/,scripts/}
```
`routing.yaml` appears only when route data has an independent owner; root/tool entry and registration surfaces appear only for proven readers. Existing root entries are preserved. Emitted routed entries use a generated `routing.yaml` bootstrap; direct entries point to the sole `SKILL.md` procedure. Cursor registration exists only when Cursor is detected, declared, currently used, or explicitly requested. See [REFERENCE.md](REFERENCE.md) for sources.
## Core Principles
1. **Single concise entry** — `SKILL.md` keeps a dual budget: description ≤ 25 lines (trigger phrases + activation) + body ≤ 90 lines (navigation); it navigates, not exhausts. ✓ Check: smoke-test reports both separately; over either → split intent clusters / move detail to sub-files.
2. **One skill folder when a folder is admitted** — folder-light and broad results keep formal docs under `skills/<name>/`; a direct result may remain a complete single `SKILL.md` carrier. ✓ Check: no emitted root entry becomes a second rule/workflow owner.
3. **Rules ≠ Flows** — `rules/` for constraints, `workflows/` for procedures. ✓ Check: any numbered steps in `rules/`, or "always/never" in `workflows/`, = mixing.
4. **Routing.yaml as source when admitted** — a direct carrier owns its sole route in `SKILL.md`; multiple/shared routes live only in `routing.yaml`, with routed shells generated from it. ✓ Check: is there an independent selector or consumer that justifies the manifest, and does its fitted sync check pass?
5. **Harness surfaces follow readers** — create/merge only entries and registrations supported by existing files/config, the current harness, repository/team declaration, or an explicit request. ✓ Check: can every emitted surface name its reader, and was every existing entry preserved?
6. **Progressive Rigor** — three carriers (Single-file / Folder-light / Full) grow only under pressure and are not user package choices. ✓ Check: can you name the independent responsibility that forced every generated file?
7. **Description = coarse activation** — domain boundary + real user trigger phrases; never enumerate workflow keywords nor summarize a workflow's steps. ✓ Check: can `routing.yaml` task routes change without rewriting the description, and does no description/label carry HOW an agent could act on without opening the body?
8. **Gotchas are highest-value** — maintain costly pitfalls actively; keep them discoverable. ✓ Check: is each high-cost gotcha activated by the admitted route owner (`SKILL.md` or `routing.yaml`), not only buried in `references/`?
9. **Progressive disclosure** — every loaded file needs an independent task-time reason; conditional content leaves the startup read set; files every real caller co-loads should merge unless ownership/generation requires separate storage. ✓ Check: for each route read, can you name a request that needs it now and a next action it changes? No → conditionally route, merge, or remove.
10. **Task Execution + Closure** — only one clear read-only or fixed-contract maintenance action with no new desired behavior executes directly; anything that adds or changes user-visible behavior, a business flow/state, or an external contract follows `requirement-ready -> Task Anchor -> implementation-ready -> Native Plan -> mutation`; Present alignment proportionally and run a compact Anchor Checkpoint before each main step. Workflow is the domain procedure; Native Plan is only this Session's runtime step owner, with no planning-file persistence. Full protocol: [references/protocols.md § Task Execution Protocol](references/protocols.md#task-execution-protocol).
11. **Durable-record rule** — generic records generalize across projects; business global models stay project-specific but must survive implementation replacement. ✓ Check: use the destination's test—cross-project pattern or cross-implementation business truth—without mixing code details into either ([ref](references/protocols.md#generalization-rule)).
12. **Self-maintenance** — line counts signal evaluation, not automatic action; split only for independently selected tasks; merge files universally co-loaded/co-changed unless ownership or generation explains the boundary. ✓ Check: can the before/after load matrix prove less irrelevant reading without losing definitions, conditions, boundaries, or reasons?
13. **Activation over storage** — content in `references/` alone is not "captured"; it must be on the task path **and change what the agent does when read**; reached-but-inert (correct, on-route, yet the agent would have proceeded identically) is a distinct failure no structural gate can see, only judgment can. ✓ Check: trace the normal route — does hitting the entry change the next action (a file read, a check run, a step skipped)?
14. **Token efficiency** — Always Read defaults to empty; every addition needs proof that all real tasks require it before workflow selection; domain and lifecycle knowledge loads only when evidence or a phase boundary can change the next action. ✓ Check: can any startup read be delayed without changing the first workflow decision? If yes, move it to that workflow checkpoint.
15. **Rationalizations Table** — captures verbatim excuses from real pressure-test failures only. ✓ Check: every row traces to a real failure — no failure observed and unwilling to baseline it → imagined-pain, drop it ([ref](templates/skill/workflows/task-closure.md#rationalizations-to-reject), [Phase 9](workflows/full-migration.md#phase-9-pressure-test-the-skill)).
16. **Response discipline** — output short, precise, direct answers; avoid process narration, self-congratulation, gratuitous confirmations, and requirement restatement. ✓ Check: does each sDiscussion
Ask, share a tip or report that it does not work. Sorted by what people marked helpful.
No posts yet. Be the first to ask or share.
Posts here are written by users, not the PopNx team.
From GitHub
- GitHub stars
- 625
- Maker
- WoJiSama
- License
- MIT
- Last code change
- Nov 13, 2026
- SKILL.md files in the repo (including translated copies and templates)
- 2
- Topics
- agent, ai, chatbot, claude, markdown, skill, spec