skill-orchestration-system
AGENTS.md10 starsChanged 6 months agoMITView on GitHub
Skill Orchestration System (SOS) is a Python CLI for organizing agent skills into auditable, activatable packs. It scans skill folders, proposes functional packs, writes reviewable plans, applies migrations only with explicit confirmation, generates sos-* pointer skills, and creates backups before writes. This is the canonical public repository. Public files must stay free of personal paths, private workspace details, tokens, account data, and local planning logs. Local NHK, planning, spec, and archive surfaces may exist in this checkout, but they are…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- sosSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
24 rules. About 0 are common, 20 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈20
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Start with the smallest current surface that can route the task safely:
- Distinctive: line 36
Do not hardcode local absolute paths or user-specific defaults.
- Distinctive: line 42
Never mutate state objects.
- Distinctive: line 49
Do not delegate deterministic validation to heuristic or probabilistic flows unless the human explicitly approves that tradeoff.
- Distinctive: line 53
If code, tests, and active project documents disagree, resolve intended behavior first.
- Distinctive: line 58
If a todo list, task list, checklist, plan, or other active tracking surface is in use, update it when each task is completed.
- Distinctive: line 59
Do not batch all task-list updates at the very end if task-by-task updates are practical.
- Very specific: line 60
If task_plan.md, progress.md, or findings.md are active, keep them aligned with actual task status.
- Very specific: line 64
After a full superpowers workflow cycle or another clearly bounded implementation cycle, check whether the active docs and tracking …
- Very specific: line 65
If the workspace is NHK-managed and the workstream looks complete, ask whether nhk-archive should be invoked.
- Distinctive: line 66
Do not archive automatically.
- Distinctive: line 71
Prefer current code, current tests, and active docs first.
- Distinctive: line 72
Start with the smallest active document set that can route the task safely.
- Distinctive: line 83
Do not close a subagent just because a wait timed out.
- Distinctive: line 84
Before replacing or closing a subagent, confirm its actual status, current progress, latest conclusion, and whether keeping it alive still …
- Distinctive: line 89
Prefer one primary objective, one main module or surface area, and one verification path per packet.
- Distinctive: line 91
If two packets share the same primary production file or test file, default to serial execution unless the plan explains why parallel work …
- Distinctive: line 92
If a packet grows across unrelated concerns, long execution chains, or multiple verification paths, split it again.
- Distinctive: line 96
When blocked during implementation:
- Distinctive: line 103
Stop and wait for the human if the fix would change public CLI semantics, pack merge authority, hidden-library write behavior, source …
- Distinctive: line 112
Default full verification is:
- Very specific: line 126
Commit format should use conventional prefixes such as feat:, fix:, docs:, test:, refactor:, or chore:.
- Distinctive: line 128
Before public commits, check:
- Distinctive: line 135
If a sensitive file was accidentally tracked, stop and remove it from the index before pushing.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Instructions
Project Overview
Skill Orchestration System (SOS) is a Python CLI for organizing agent skills into
auditable, activatable packs. It scans skill folders, proposes functional packs,
writes reviewable plans, applies migrations only with explicit confirmation,
generates sos-* pointer skills, and creates backups before writes.
This is the canonical public repository. Public files must stay free of personal paths, private workspace details, tokens, account data, and local planning logs. Local NHK, planning, spec, and archive surfaces may exist in this checkout, but they are intentionally ignored by Git.
Workspace Navigation
Start with the smallest current surface that can route the task safely:
AGENTS.mdfor stable execution rules.coding-agent-guide.mdfor local task routing, when present.documentation-governance.mdfor local active/archive rules, when present.task_plan.md,findings.md, andprogress.mdonly when they are active.README.md,README_CN.md,references/,src/, andtests/for public product work.
Ignored local workflow files include task_plan.md, progress.md,
findings.md, coding-agent-guide.md, documentation-governance.md, docs/,
and archive/. They are useful for local continuity but must not be committed.
Architecture Boundaries
- CLI writes must stay deterministic, auditable, and dry-run-first.
scan,propose, and dry-run commands must not mutate active skill roots.- Config, manifest, vault, backup, restore, sync, and source deletion behavior must be covered by tests.
- Source deletion must remain opt-in and require explicit confirmation.
- Pointer skills should remain short routing surfaces; full skill content belongs in the managed vault.
- Do not hardcode local absolute paths or user-specific defaults.
- Host-specific disable behavior must stay isolated to operation kinds (
MOVE_TO_ARCHIVEfor Claude,DISABLE_CODEX_SKILLfor Codex) and validated inapply._validate_planbefore any write.
Mandatory Execution Rules
Immutable Data Patterns
- Never mutate state objects. Always return new copies.
const newState = { ...oldState, field: newValue }- Array operations:
slice,map,filter— neversplice,push,sortin-place.
Deterministic Boundaries Must Stay Deterministic
- Validation, schema checks, path checks, reference integrity, and persistence guarantees should be handled by deterministic code.
- Do not delegate deterministic validation to heuristic or probabilistic flows unless the human explicitly approves that tradeoff.
Keep Rules, Code, Tests, and Active Docs in Sync
- If code, tests, and active project documents disagree, resolve intended behavior first.
- Then bring implementation, tests, and active docs back into sync.
Task Tracking Discipline
- If a todo list, task list, checklist, plan, or other active tracking surface is in use, update it when each task is completed.
- Do not batch all task-list updates at the very end if task-by-task updates are practical.
- If
task_plan.md,progress.md, orfindings.mdare active, keep them aligned with actual task status.
Workflow Completion and Archive Check
- After a full
superpowersworkflow cycle or another clearly bounded implementation cycle, check whether the active docs and tracking surfaces suggest that a workstream may be complete. - If the workspace is NHK-managed and the workstream looks complete, ask whether
nhk-archiveshould be invoked. - Do not archive automatically.
Documentation Governance and Context Loading
documentation-governance.md, when present, is the source of truth for local documentation lifecycle rules.- Prefer current code, current tests, and active docs first; treat archive as reference material rather than a default execution source.
- Start with the smallest active document set that can route the task safely.
- Load specs, plans, codemaps, or archive only when the task genuinely needs them.
- For root tracking discipline, use
planning-with-files-zhwhen the work is multi-session or needs durable recovery. - For active specs, plans, TDD, review loops, and implementation workflows, use the relevant
superpowersskills.
Subagent Delegation Discipline
- For complex work, prefer decomposing implementation into bounded tasks and dispatching subagents when the subtasks are independent enough.
- Subagent dispatch must follow
subagent-driven-development; do not improvise a parallel workflow outside that discipline when the task has already been decomposed. - Dispatch instructions must state whether the subagent is read-only review or write-authorized implementation.
- Give each subagent a clean task brief, owned files or modules, verification expectations, and forbidden actions.
- Do not close a subagent just because a wait timed out.
- Before replacing or closing a subagent, confirm its actual status, current progress, latest conclusion, and whether keeping it alive still reduces risk or rework.
Implementation Packet Discipline
- Decompose implementation work into bounded packets before dispatch.
- Prefer one primary objective, one main module or surface area, and one verification path per packet.
- Each packet should declare its user-facing goal, owned files, default verification command, and whether it is safe to run in parallel.
- If two packets share the same primary production file or test file, default to serial execution unless the plan explains why parallel work is still safe.
- If a packet grows across unrelated concerns, long execution chains, or multiple verification paths, split it again.
Blocker Protocol
When blocked during implementation:
- Field missing producer -> add the producer.
- Output has no downstream entry -> add to the nearest shared contract.
- Code forced to understand semantics -> convert to a staged responsibility boundary.
- Naming conflict -> prefer the current SOS canonical name, then sync code, tests, docs, and plans.
Stop and wait for the human if the fix would change public CLI semantics, pack merge authority, hidden-library write behavior, source deletion behavior, or the human-confirmation control model.
Testing and Verification
- For feature or bugfix work, use test-driven development: write or update tests first, confirm failure when practical, implement, then confirm green.
- For documentation-only changes, run reference checks such as
git diff --check, file existence checks, and privacy scans for public content. - For code changes, run the relevant targeted tests first, then the full test suite before calling work complete.
- Default full verification is:
python -m pytest- CLI smoke check:
python -m sos --versionGit and Delivery
- Commit format should use conventional prefixes such as
feat:,fix:,docs:,test:,refactor:, orchore:. - Public commits must not include ignored local planning files, local absolute paths, private notes, generated runtime state, caches, or virtual environments.
- Before public commits, check:
git status --short --ignored
git diff --check- If a sensitive file was accidentally tracked, stop and remove it from the index before pushing.
- Human review is required before broad merges, public behavior changes, or irreversible write-path changes.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

