capture-subsystem
Capture a stable subsystem's mental model, invariants, and key files as a reusable skill after deep research. Use for durable subsystem knowledge; use artifact-logging for ephemeral findings.
- License 许可
- MIT
- 所属仓库
- xiaden/SkyScow
- 最近更新
- 2026-09-30
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- capture-subsystem
- description
- Capture a stable subsystem's mental model, invariants, and key files as a reusable skill after deep research. Use for durable subsystem knowledge; use artifact-logging for ephemeral findings.
02 资源文件 1
- 参考文档references/examples.md6.4 KB
03 SKILL.md 正文
Capture Subsystem
You have just done expensive research on a stable subsystem. Capture the mental model now — once — rather than rediscovering it every session.
Check Before Creating
Before creating a new skill, check if one already exists for this subsystem. Skills live in {project_skills_dir} and {tooling_skills_dir}. If a skill exists:
- Extend it with what you just learned — do not create a duplicate
- Update the
## Coveragesection - If you learned something that contradicts the skill, fix the skill and note the change
A partial skill that labels its gaps is always preferable to no skill. A partial skill with unlabeled gaps causes confident wrong reasoning — worse than no skill.
What Belongs
A subsystem skill answers: "What does a competent engineer need to know before touching this area?"
Include:
- The intended mental model — why this architecture, not just what it does
- Process/thread/IPC topology (who owns what, how parts communicate)
- Key invariants an agent must not violate
- Which files are canonical owners of each concern
- How the subsystem connects to the rest of the system (entry/exit points)
- Citations to the governing decisions (from the
architecture-decisionsskill) and prior design docs that motivated the design
Do not include:
- Implementation details that change with normal refactors (method signatures, variable names)
- Information already obvious from reading one file
- Anything the model already knows (Python stdlib, FastAPI patterns, etc.)
- Episodic history ("we tried X and it failed") — that belongs in logs/process history
The Test
If an agent reads all the files in the subsystem but still doesn't know why it's structured this way or what would break if they changed it naively — the gap belongs in a skill.
Structure
Place project-specific subsystem skills in {project_skills_dir}/{subsystem-name}/SKILL.md.
Place generic/tooling skills in {tooling_skills_dir}/{skill-name}/SKILL.md.
{project_skills_dir}/my-subsystem/
├── SKILL.md ← frontmatter + mental model + key files table + invariants
└── references/ ← optional: full topology, schema, edge cases if large
└── architecture.md
Keep SKILL.md scannable — the body should contain what every invocation needs. Move detailed examples, topology diagrams, and edge cases to references/ and link them.
Required Sections
Every subsystem orientation skill must include these sections, in order:
- One-paragraph mental model — the "explain it to a new hire in 60 seconds" summary
- Coverage — formal declaration of what this skill documents and what it does not
- Key Files table — area → canonical file, no descriptions, just the map
- Critical Invariants — the things an agent must never break, stated as constraints
- Common Task Patterns (optional) — if there are 2-3 stereotyped tasks that are easy to get wrong
Coverage Section Format
Every subsystem skill must include a ## Coverage section immediately after the mental model. This is the staleness and incompleteness signal for future agents.
## Coverage
**Documented:** <comma-separated list of concerns this skill covers>
**Not yet documented:** <comma-separated list of known gaps, or "none known">
**Last extended:** YYYY-MM-DD
Rules:
Documentedlists specific concerns — not the subsystem name, the concernsNot yet documentedlists known gaps — areas that exist in the subsystem but weren't researched yetLast extendedis the ISO date the skill was last written or extended- When extending a skill, move items from
Not yet documentedtoDocumented, and add new gaps discovered - If
Not yet documentedis empty, writenone known— do not omit the field
Frontmatter Discipline
The description field is the trigger selector. It must:
- Name the subsystem explicitly (agents match on nouns)
- List the tasks that should load it, not just the domain
- Be specific enough that it doesn't load for every session
See [references/examples.md](file:///home/opencode/.config/opencode/skills/capture-subsystem/references/examples.md) for good and bad description examples with explanations, plus a full annotated example of a well-structured subsystem skill.
Source Citations
Every skill must cite its authoritative sources. Include at the bottom:
## Sources
- ADR-NNN: Title
- DD: slug (artifacts/designs/...)
If no governing decision or prior design doc exists for the design decision, that's a gap worth noting — the skill can serve as informal documentation until a proper record is committed through the artifact-logging workflow.
Staleness Contract
A skill is a view over governing decisions and design docs. When the underlying design changes:
- The governance-record supersession and the skill update must be in the same commit
- If the skill becomes stale, it causes confident wrong reasoning — worse than no skill
- Always include a
## Sourcessection so future maintainers know which governance records to check
References
- [
references/examples.md](file:///home/opencode/.config/opencode/skills/capture-subsystem/references/examples.md) — Full annotated example, good/bad description patterns, and when NOT to create a skill - Related skills:
making-editing-skills(skill structure conventions),artifact-logging(logging conventions)
Base directory for this skill: /home/opencode/.config/opencode/skills/capture-subsystem
04 同仓库更多 Skills
unquoted-colon
暂无简介
quoted-description
Use when a plain scalar contains a colon: like this one.
block-description
Use when a plain scalar contains a colon: like this one.
work-routing
Canonical authority for who owns the next unit of work — direct work versus delegation, task tiers, bounded localization, the Change DAG size threshold, R&D evaluation routing, progressive research escalation, researcher scope signals, and QA/support owner selection. Use before choosing execution, investigation, design, or QA ownership; do not use to construct dispatch prompts, handoff schemas, or Change DAG/DD tool operation.
update-docs
Update project documentation to match code changes — generate codemaps, refresh READMEs, detect doc/code drift using AST analysis. Use when updating documentation after code changes, generating codemaps, verifying doc accuracy, or detecting stale documentation. Do NOT use for writing API reference docs from scratch (use doc-coauthoring) or for creating new skill files (use making-editing-skills).
skill-loading-system
Explain or troubleshoot OpenCode skill discovery, loading, permissions, availability, or prompt injection.