Executable, bilingual pattern-transfer records for the Skillware paper.
简体中文 · Paper · Release v0.1-paper-v1 · Browse patterns
Skillware is the software abstraction that extends software engineering to persistent behavioral artifacts. The paper argues that a Skill can be treated as software when its behavioral source is persistent, independently addressable, host-activated, and maintained through a software lifecycle.
This repository is the executable supplement for one bounded part of that argument: transferring established software design patterns to Skillware units and recording what the evidence does and does not support.
The release also includes the public evidence supplement used by the paper:
the frozen corpus metadata, 15-case category-boundary matrix, coding protocol,
and 13 fixed-revision engineering packets under evidence/paper-v1/.
flowchart LR
I[Task intent] --> S[Behavioral Source]
S --> A[Skill Artifact\nSKILL.md + optional resources]
A --> U[Skillware Unit\nidentity + version + provenance]
U --> H[Agent Host\nactivation and context]
H --> R[Agent Runtime\ninterpretation and tool use]
R --> T[Execution Trace]
T --> O[Task Outcome]
P[Source pattern\nintent + forces + participants] --> M[Participant map]
M --> A
E[Evidence boundary\npinned paths + tests + misuse case] -. qualifies claims .-> M
The Python samples execute deterministic oracles for declared contracts. They do not emulate a model, an Agent Host, or an Agent Runtime; those remain contextual execution concepts in the ontology.
Boundary shorthand: Behavioral Source -> Skill Artifact -> Skillware Unit -> Agent Host -> Agent Runtime.
- A self-contained research artifact tied to arXiv:2607.18970.
- A sourced screen of all 23 Gang of Four patterns, with 10 detailed GoF implementations.
- Twelve standalone records: six main-text GoF mappings, four supplementary GoF mappings, and two established non-GoF traditions.
- Bilingual definitions, participant maps, public fixed-revision correspondence records, runnable Skill examples, close misuse cases, and focused tests.
- Not a new design-pattern taxonomy and not a claim to invent GoF, POSA, or DDD patterns.
- Not a marketplace, Skill registry, Agent Host, Agent Runtime, model benchmark, or production reliability study.
- Not evidence that a local deterministic sample reproduces upstream model behavior or proves cross-Host equivalence.
- Not a maturity ladder: pattern, implementation dimension, mechanism, and lifecycle stage remain separate analytical axes.
| Surface | Contents | Start here |
|---|---|---|
| Definitions | English and Chinese source-pattern definitions plus Skillware participant maps | patterns/<pattern>/definition.md |
| Ecosystem evidence | Public upstream links frozen to immutable commits and a controlled claim status | correspondence.md |
| Complete Skills | Root SKILL.md, child Skills or target bindings, references, scripts, fixtures, and expected results | Facade sample |
| Verification | Focused tests, misuse discriminators, catalog checks, documentation checks, and repository validator | tests/ · scripts/validate_repository.py |
| Paper binding | Claim-level mapping from paper Table 5 to local records and release | docs/paper-map.md |
| Scope | Count | Interpretation |
|---|---|---|
| 23 GoF patterns screened | 23 | One sourced screening record for every canonical Gang of Four pattern; screening is not implementation. |
| 10 detailed GoF implementations | 10 | Facade, Adapter, Composite, Observer, State, Strategy, Decorator, Template Method, Memento, and Mediator. |
| 2 patterns from other established traditions | 2 | POSA Pipes and Filters and DDD Specification; they are labeled separately from GoF. |
| Language | Python 3.10+ | Samples use the standard library; PyYAML is used by catalog tooling and the validator. |
| Release binding | v0.1-paper-v1 | The public repository release bound to the paper revision described in docs/paper-map.md. |
git clone https://github.com/MetaInFLow/skillware-patterns.git
cd skillware-patterns
python3 patterns/facade/sample/scripts/run_demo.pyThe Production Incident Response Facade accepts one stable request and coordinates three specialist Skills. The output is deterministic and should match incident-result.json:
{
"summary": "checkout-api is experiencing elevated 5xx responses.",
"impact": "Customer requests may fail; treat checkout availability as degraded.",
"actions": [
"page-on-call",
"inspect-recent-deployments",
"check-upstream-dependencies"
],
"communication": "Investigating elevated 5xx responses for checkout-api; customer impact is being assessed."
}Read the complete root Skill, participant map, misuse case, and focused tests to see how the mapping is made concrete. Every other pattern directory has the same inspectable record shape, with Adapter documenting three target bindings instead of separate child Skills.
This release separates what is implemented locally from what is observed in public upstream artifacts.
| Surface | Status | Meaning |
|---|---|---|
| Twelve local samples | constructive | The repository demonstrates that the declared Skillware mapping can be built and tested deterministically. |
| Facade ecosystem case | confirmed correspondence | The pinned Superpowers source paths satisfy the recorded participant relation. |
| Adapter ecosystem case | confirmed correspondence | The pinned gstack source paths show explicit host-target bindings; runtime parity still needs tests. |
| Composite, Observer, State, Strategy, Decorator, Template Method, Memento, Mediator, Pipes and Filters | candidate correspondence | Some source-level participants or behaviors remain unverified at the frozen paths. |
| Specification ecosystem case | not observable | No public artifact was admitted as a bounded Specification correspondence in this release. |
| Model interpretation and cross-Host behavior | out of scope | Python oracle output cannot establish these claims. |
Statuses are descriptive claim labels, not scores. See the full status vocabulary and limitations.
The twelve records are peers in one flat navigation tree. source_tradition, source_category, paper_role, and implementation_status live in each pattern.yaml; the source category is metadata, not a second taxonomy.
| Pattern | 中文名 | Tradition / category | Scenario | Ecosystem status | Upstream example | Local sample |
|---|---|---|---|---|---|---|
| Facade | 外观模式 | GoF / structural | Production Incident Response | confirmed correspondence | Superpowers using-superpowers | sample |
| Adapter | 适配器模式 | GoF / structural | Multi-Tracker Issue Publisher | confirmed correspondence | gstack host bindings | sample |
| Composite | 组合模式 | GoF / structural | Investment Memo Builder | candidate correspondence | OpenMontage pipeline | sample |
| Observer | 观察者模式 | GoF / behavioral | Software Release Notification | candidate correspondence | ECC lifecycle hooks | sample |
| State | 状态模式 | GoF / behavioral | Vendor Onboarding Workflow | candidate correspondence | OpenMontage checkpoints | sample |
| Strategy | 策略模式 | GoF / behavioral | Risk-Aware Code Review | candidate correspondence | UI/UX Pro Max routing | sample |
| Decorator | 装饰模式 | GoF / structural | Contract Review Enhancers | candidate correspondence | Caveman activation hook | sample |
| Template Method | 模板方法模式 | GoF / behavioral | Enterprise RFP Response | candidate correspondence | Superpowers workflow Skills | sample |
| Memento | 备忘录模式 | GoF / behavioral | Configuration Migration | candidate correspondence | Microsoft SkillOpt staging | sample |
| Mediator | 中介者模式 | GoF / behavioral | Deployment Coordinator | candidate correspondence | Anthropic financial-services reconciler | sample |
| Pipes and Filters | 管道-过滤器模式 | POSA / architectural | Support Ticket Triage | candidate correspondence | OpenMontage animated-explainer pipeline | sample |
| Specification | 规约模式 | DDD / domain | Expense Approval Policy | not observable | No admitted upstream case | sample |
The GoF-23 screening matrix records the other thirteen GoF patterns as screening records only. The detailed index is the machine-rendered catalog source.
Each link below names the concrete public Skill, hook, pipeline, binding, or staging path inspected for the corresponding record. Star counts are discovery snapshots checked 2026-07-23; they help readers find important ecosystem examples but are not evidence strength, quality ratings, or paper results. Every evidence record pins an immutable revision.
| Pattern | Public project | Snapshot | Exact inspected use |
|---|---|---|---|
| Facade | obra/superpowers | ~259k stars | skills/using-superpowers/SKILL.md selects and invokes specialist Skills; hooks/session-start bootstraps discovery. |
| Adapter | garrytan/gstack | ~124k stars | SKILL.md.tmpl, scripts/gen-skill-docs.ts, and hosts/codex.ts bind one Skill contract to a host target. |
| Composite | calesthio/OpenMontage | ~41.2k stars | pipeline_defs/animation.yaml and its stage Skills are loaded by lib/pipeline_loader.py. This remains a candidate because the reviewed tree does not establish a complete one-parent composite contract. |
| Observer | affaan-m/Everything Claude Code | ~232k stars | hooks/hooks.json routes lifecycle events to run-with-flags.js and continuous-learning-v2/hooks/observe.sh. |
| State | calesthio/OpenMontage | ~41.2k stars | lib/checkpoint.py and skills/meta/checkpoint-protocol.md persist stage/status branches. Full GoF delegation is not established. |
| Strategy | nextlevelbuilder/ui-ux-pro-max-skill | ~109k stars | SKILL.md routes through scripts/search.py; alternatives lack a single declared substitution contract. |
| Decorator | JuliusBrussee/caveman | ~92.1k stars | src/hooks/caveman-activate.js wraps activation with the skills/caveman/SKILL.md guidance; a complete GoF Component contract is not declared. |
| Template Method | obra/superpowers | ~259k stars | skills/brainstorming/SKILL.md and skills/test-driven-development/SKILL.md share ordered process guidance; bounded specialization hooks remain unverified. |
| Memento | microsoft/SkillOpt | ~14.5k stars | skillopt_sleep/staging.py backs up a staging manifest before adoption; the inspected path does not expose a complete owned restore protocol. |
| Mediator | anthropics/financial-services | ~33.7k stars | managed-agent-cookbooks/gl-reconciler/agent.yaml coordinates reader, critic, and resolver subagents; the release coordinator is a candidate mapping. |
| Pipes and Filters | calesthio/OpenMontage | ~41.2k stars | pipeline_defs/animated-explainer.yaml orders stage Skills loaded by lib/pipeline_loader.py. |
| Specification | — | — | No public upstream artifact was admitted as a bounded Specification correspondence; see the negative evidence record. |
The local evidence files explain what each path proves, what it does not prove, and why the controlled status is not stronger. They are not vendor endorsements and do not copy upstream code.
Every detailed pattern is a compact, inspectable Skillware record:
pattern.yaml source name, Chinese name, tradition, role, scenario
definition.md source intent, forces, participants, consequences
definition.zh-CN.md Chinese definition with the same claim boundary
participant-map.yaml source participant -> Skillware participant relation
correspondence.md public revision, exact paths, status, caveats
evidence/ frozen upstream evidence when a public case is admitted
sample/SKILL.md complete root Skill and its public request/result contract
sample/child-skills/ specialist Skills, when the scenario uses them
sample/references/ schemas, policies, and reusable reference material
sample/scripts/ deterministic oracle and demo entry point
sample/fixtures/ positive and negative inputs
sample/expected/ versioned expected outputs and errors
sample/tests/ focused verification of behavior and boundaries
misuse/ close non-example and decisive discriminator
The Facade record is the shortest route through all seven parts. The Adapter record shows how one canonical Skill request can be rendered into GitHub REST, Jira REST/ADF, and Linear GraphQL target contracts.
A pattern-transfer claim is admitted only when one declared Skillware Unit and revision records all seven elements in the transfer protocol:
Source intent
Design forces
Participant correspondence
Consequences
Implementation evidence
Focused verification
Misuse discriminator
Names, filenames, comments, or visual resemblance do not establish a transfer. A local sample can be constructive even when public ecosystem correspondence remains candidate correspondence or not observable.
Python 3.10+ is required. A clean checkout can run the sample without network access or credentials; install PyYAML before catalog-dependent checks:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .# One sample, then focused and full verification
python3 patterns/facade/sample/scripts/run_demo.py
python3 -m unittest discover -s patterns/facade/sample/tests -v
python3 -m unittest tests/test_docs.py -v
python3 -m unittest discover -s tests -v
python3 scripts/validate_repository.pyEvery sample is designed to run from the repository root or its own sample directory and uses Python's standard library for its executable oracle. The validation workflow repeats the repository checks on pushes and pull requests; a workflow badge is a live status indicator, not a paper result.
catalog/ GoF-23 screen and detailed machine/human indexes
docs/ ontology, paper map, protocol, statuses, limitations
evidence/paper-v1/ public paper evidence: corpus, boundary review, engineering cases
patterns/<pattern>/ one flat, independently inspectable pattern record
definition*.md English and Chinese source definitions
participant-map.yaml source-to-Skillware participant correspondence
correspondence.md public evidence and bounded claim status
evidence/ pinned upstream case files, where available
sample/ complete Skill, resources, oracle, fixtures, tests
misuse/ close non-example and discriminator
scripts/ deterministic catalog/repository validator
tests/ documentation, shape, catalog, record, and sample tests
The public paper Skillware: A Software Ontology and Engineering Lifecycle for Persistent Behavioral Artifacts defines the ontology and motivates software-engineering continuity. This repository publishes the transfer protocol, sourced catalog, participant maps, public frozen cases, constructive samples, misuse cases, and focused verification for release v0.1-paper-v1.
The paper's manuscript source remains maintained in a private authoring repository. This public repository carries the paper-bound evidence subset required to inspect the published claims; it cannot validate the ontology or establish ecosystem prevalence by itself.
| Status | Meaning |
|---|---|
constructive | The local sample demonstrates that the declared mapping can be built and tested. |
confirmed correspondence | Fixed-revision public source evidence satisfies the participant relation. |
candidate correspondence | Partial source evidence exists, but a participant or behavior remains unverified. |
unsupported | Available evidence contradicts or fails the source pattern contract. |
not observable | The required relation cannot be evaluated from available artifacts. |
These statuses are descriptive, not a score. They do not rank patterns, projects, usefulness, quality, or maturity.
The artifacts demonstrate bounded constructibility and, where stated, fixed-revision correspondence. They do not establish ecosystem frequency, automatic quality advantage, production reliability, security, comparative performance, model interpretation, or cross-Host behavioral equivalence. Deterministic oracles verify declared sample contracts; they do not reproduce an Agent Runtime or prove that natural-language interpretation is invariant.
See the complete evidence vocabulary and limitations.
Haodi Fan and Zucong Lan. Skillware: A Software Ontology and Engineering Lifecycle for Persistent Behavioral Artifacts. arXiv:2607.18970 [cs.SE], submitted 21 July 2026.
For software citation metadata, use CITATION.cff. For claim-level paper paths, use docs/paper-map.md. The release that binds this supplement to the public paper is v0.1-paper-v1.
Start with CONTRIBUTING.md. New records must preserve an established source tradition, exact participant map, bilingual definitions, a complete standalone Skill sample, a close misuse case, focused tests, the seven-element admission protocol, and a controlled claim status. Contributions should distinguish public upstream evidence from local constructive evidence and must not treat a pattern name as proof.
This repository runs local deterministic examples and does not require secrets, network access, or third-party service credentials. Do not place credentials in fixtures or correspondence records. Report a security issue through the private GitHub security reporting page rather than opening a public issue.
- Open issues for reproducible defects or documentation corrections.
- Pull requests for reviewed changes.
- Code of Conduct for participation norms.
- Paper for the ontology and research claims.
The operative file boundary is exhaustive and disjoint:
Apache-2.0
.github/**
.gitignore
pyproject.toml
scripts/**
tests/**
patterns/*/sample/**
CC-BY-4.0
README.md
README.zh-CN.md
CITATION.cff
CONTRIBUTING.md
CODE_OF_CONDUCT.md
catalog/**
docs/**
patterns/.gitkeep
patterns/*/** excluding patterns/*/sample/**
Canonical upstream texts (outside repository relicensing)
LICENSE-CODE
LICENSE-DOCS
The Apache-2.0 class is licensed under the Apache License 2.0; the CC-BY-4.0 class is licensed under Creative Commons Attribution 4.0 International. LICENSE-CODE and LICENSE-DOCS retain their canonical upstream texts and are outside repository relicensing. Linked third-party artifacts remain under their upstream licenses. See CONTRIBUTING.md#license-boundary for contribution terms.