concept-skills

Give functionality boundaries. Make coordination visible.

Adding a share feature can touch posting, authorization, and notification code. When the connections are scattered, the effects of a change are hard to see.

concept-design supports software design and AI coding with Daniel Jackson’s concepts and synchronizations. Start from a user’s need, define independent modules and explicit coordination rules, then use them for specifications, implementation, review, and Mermaid maps. Adapts ideas from WYSIWID (Meng & Jackson, MIT).

🧩 How it works

• Concepts provide independent functionality with their own state and actions; concepts do not call one another or read one another’s state.
• Synchronizations make coordination explicit: what happened, which conditions hold, and which actions follow.
• LLMs and the CLI have separate roles: an LLM generates or changes code from specifications, the CLI checks specification structure, and review and tests check behavior.

For example: comment created → query the post’s author → send a notification. The synchronization holds the coordination; Comment need not depend on Notification.

✨ What it helps with

Locate functionality, change concepts independently, and read coordination rules directly. Before adding a feature, consider reusing concepts or changing a few synchronizations, then check that existing behavior is preserved. The goal is more modular, transparent, and understandable software. See the MIT report for background. See sources for theory and local choices.

Get started

From this repository, install one language edition:

npx --yes skills add . --skill concept-design --agent codex --copy --yes
npx --yes skills add . --skill concept-design-cn --agent codex --copy --yes

Invoke explicitly; only the workflow needed for the task is read:

$concept-design design Define concepts and synchronizations for reservations.
$concept-design build Implement the confirmed specifications.
$concept-design review src/orders Inspect concept boundaries and code, read-only.
$concept-design guard map src Generate a concept and synchronization diagram.

Also supports settle, prd, guard, refine, and explain; Chinese uses $concept-design-cn.

What concept-lint checks

Read-only, with no third-party dependencies. Checks the skill’s local CONCEPT/SYNCS notation:

python3 skills/en/concept-design/scripts/concept_lint.py CONCEPT.md SYNCS.md --json

Checks declarations and core sections, when/then completion and invocation shapes, top-level named fields, and rule-name uniqueness for each app across the supplied files. Unknown or legacy call notation is unchecked; types, bindings, concept independence, and runtime results still require other evidence. Exit codes: 0 passed the listed checks, 1 format error, 2 read/usage error, 3 not checked.

Generate a concept and synchronization diagram

Scan CONCEPT.md and SYNCS.md to produce one ARCHITECTURE.md with a concept index, Mermaid diagram, relation table, and source lines. Definitions, instances, and synchronization rules have separate identities; unresolved references remain gaps.

python3 skills/en/concept-design/scripts/concept_map.py  --output /ARCHITECTURE.md

Use --scope RELPATH to narrow the view or --check to compare without writing. Existing documents retain text outside the generated region. See the map format.

Repository skills

Data semantics, personal knowledge management, and learning remain separate skills; each has English and Chinese editions.

Maintenance and license

The former eight concept-design workflows share one entry per language. Current skill version: 2.0.1. Repository version: 3.0.1. Old ClawHub entries redirect to the matching language edition where possible; the rest are retired or already unavailable. Preserve project specifications, code, and user configuration during migration.

Run ./tools/validate-all.sh to check public packages. Repository rules · Changes · 中文. Apache-2.0; ClawHub bundles use MIT-0. Adapted material retains its MIT notice in each package.