TPMN Skill Standard

Your Claude Code skills have three structural failure modes.

Your scope decays silently — prose constraints dilute under compaction, architecture boundaries drift between sessions. No one notices. This is silent scope decay.

Your code review is performance — you review AI output but have no contract to check against, no ground truth to verify. This is judgment theater.

Your skill selection fails silently — the wrong skill fires, or no skill fires at all. No error, no warning, no log. This is trigger collision.

Each session without contracts widens the gap between what you believe was produced correctly and what verification would have confirmed. This is proof drift — invisible, compounding, silent.

TPMN Skill Standard breaks the cycle. Write contracts before you execute. Verify results against specs. Archive proven patterns into a searchable knowledge graph. Every session inherits what the last session proved.

This is the Proof Cycle — and it is the only architecture that compounds.

npx @gem_squared/tpmn-skill-install

• Claude Skills Fail Silently. Here Is My Solution.
• Three Wounds That Prose Skills Cannot Fix — The Full Analysis
• Claude Skills want ALL

Why TPMN, Not Prose

Every other skill standard uses prose descriptions. Prose has three structural failure modes that TPMN eliminates.

1. Silent Scope Decay — prose constraints erode without detection.

AI is a mathematical and logical system. Communicating engineering work to it in prose is a fundamental mismatch — and this mismatch is the root cause of silent failure.

Claude compacts long context by summarizing. Summaries lose preconditions, edge cases, mandate boundaries. "When preconditions hold, plan the work..." compacts to "Plans work" — constraints gone, silently. Architecture boundaries drift between sessions. No STATE check confirms they're intact.

TPMN is an Algebraic Logical Language (ALL) — not a formatting convention. P ≜ work ≠ ⊥ ∧ project_slug ≠ ⊥ cannot be summarized further without removing a conjunct — and removing a conjunct visibly breaks the formula. Breakage is detectable, not silent.

2. Judgment Theater — prose skills have no failure definition.

"Does it look right?" is not verification. TPMN's STATE check is deterministic:

• Field coverage — did B produce every required field?
• Type conformance — are the types correct?
• Constraint satisfaction — do the preconditions hold?

STATE = SUCCESS is structural. Not an opinion. /verify-work runs the same three checks every time, independent of who is reviewing or how long the session has been running.

3. Trigger Collision — prose-based skill selection fails silently.

The wrong skill fires, or no skill fires at all — and the failure is unobservable. Three independent studies found 23-56% failure rates in skill activation. The conventional model scales by adding skills; each new skill increases the collision surface.

TPMN solves this with two inversions:

• Lifecycle orchestration, not skill proliferation — 12 lifecycle skills handle HOW (plan, execute, verify, archive). Selection is deterministic because the set is closed.
• Knowledge compounds, not skills — every verified work-plan is a proven template. /archive-work stores it. /search-kg retrieves it. /plan-work reuses it. The lifecycle stays fixed. The knowledge compounds.

Stop growing your skill library. Grow your contract archive instead.

And: proven contracts become reusable skills. /extract-skill converts a verified work-plan into a project skill (SKILL.md) — the same format as the 12 lifecycle skills, installable in any project. Your domain knowledge becomes portable.

The Lifecycle — The Proof Cycle

/search-kg          Search proven patterns from prior work
     |
/search-skill       Discover installed + archived skills and directories
     |
/plan-work          Write CONTRACTs (A → B | P) for each unit
     |
/proceed-work       Execute one unit, verify inline, retry on failure
     |              (repeat for each unit)
     |
/verify-work        Compare Result vs CONTRACT.B (per-unit or batch)
     |
/archive-work       Move to archive/, git commit, update counters
     |
/extract-skill      Convert proven contracts into reusable skills (optional)

Every unit of work has a CONTRACT:

• A — input state: what exists before the work
• B — output state: what must exist after (always a state, never an action)
• P — precondition: what must be true to start
• Clarity % — how well-defined the scope is (0–100)

Quick Start

npx @gem_squared/tpmn-skill-install

Then in Claude Code:

Note: Skill Hygiene on First Session

When you run /init-session, TPMN automatically archives your existing non-core skills from .claude/skills/ to .gem-squared/external-skills/.

Your skills are NOT deleted. They are moved — still searchable via /search-skill and /search-kg, and restorable anytime with /skill-to-kg restore <skill-name>.

TPMN keeps only the 12 lifecycle skills + your project skill active in .claude/skills/ to eliminate trigger collision (the wrong skill firing silently).

/init-session          # bootstrap project files + detect layer
/check-session         # read-only status report
/search-kg             # search proven patterns in archive
/search-skill          # discover installed + archived skills and directories
/plan-work             # decompose work into contracted units
/proceed-work          # execute one unit, verify inline, retry on failure
/update-work-plan      # add, modify, abort, or reorder units in a live WP
/extract-skill         # convert proven WP into reusable skill
/verify-work           # verify results against contracts (per-unit or batch)
/skill-to-kg           # archive non-protected skills/dirs to external-skills (default), restore specific
/archive-work          # finalize, commit, move to archive
/end-session           # commit session state for recovery

What You Get

12 lifecycle skills — plan, execute, verify, archive, search, extract:

| Skill | What it does | When to use | |-------|-------------|-------------| | /init-session | Ensure project files exist, detect L0/L1 layer | Every session start | | /check-session | Read-only status report (counters, active WPs) | Anytime | | /search-kg | Search proven contracts and patterns in archive | Before planning | | /search-skill | Discover installed + archived skills and directories | During planning | | /plan-work | Decompose work into 1–9 units with CONTRACTs | New work request | | /proceed-work | Execute ONE unit-work, verify inline, retry on failure | After planning | | /update-work-plan | Add, modify, abort, or reorder PENDING units | Mid-execution scope change | | /extract-skill | Convert proven WP into reusable SKILL.md | After archiving SUCCESS | | /verify-work | Verify Results against CONTRACTs (per-unit or batch) | After each unit (inline) or all units done | | /skill-to-kg | Archive non-protected skills/dirs to external-skills (protects 12 core + project skill), restore specific | init-session (auto), after extract, manual | | /archive-work | Finalize WP, git commit, update alarm | After verification | | /end-session | Commit session state for recovery | End of session |

Plus:

• TPMN Skill Standard v4.1 — formal grammar for defining AI skill contracts
• Market Skills — community CONTRACT references for unfamiliar domains (see below)
• Project scaffold — .gem-squared/ directory convention with work plans, verification logs, and archive
• CLAUDE.md template — behavioral rules and session protocol
• alarm.md — mutable project state (counters, active tasks, known issues)

Market Skills

Market skills are community-published CONTRACT references. During /plan-work, /search-skill searches them alongside your local skills — giving Claude Code a CONTRACT-shaped starting point for unfamiliar domains, without adding new lifecycle commands.

Market skills are planning references, not triggers. They are never executed. They inform UC field structure (A, B, P) so your unit-contracts are grounded in proven contract shapes from day one.

Install a market skill

npx @gem_squared/tpmn-skill-install add {publisher}/{skill-name}

Examples:

npx @gem_squared/tpmn-skill-install add gem-squared/figma-tokens
npx @gem_squared/tpmn-skill-install add gem-squared/stripe-webhooks
npx @gem_squared/tpmn-skill-install add gem-squared/openapi-spec

Where market skills live

~/.gem-squared/market-skills/{publisher}/{skill-name}/SKILL.md

Global — installed once, available in every project. /search-skill searches this directory automatically during /plan-work.

Search scope during /plan-work

1. {project}/.claude/skills/          # local extracted skills   (highest priority)
2. ~/.claude/skills/                   # 12 core lifecycle skills
3. ~/.gem-squared/market-skills/       # market CONTRACT references
4. ~/.gem-squared/archive/             # proven prior WP patterns (via /search-kg)

Publish a market skill

Market skills must follow TPMN-SKILL-STANDARD v4.1 and pass the structural validation checklist (V01–V09) before listing.

npx @gem_squared/tpmn-skill-install validate ./my-skill/SKILL.md

Submit via: github.com/gem-squared/tpmn-market

Directory Structure

your-project/
  .gem-squared/
    alarm.md                    # mutable state — counters, active tasks
    work-plan/                  # active WP files (WP-{slug}-{N}.md)
    verify-work-logs/           # verification results per WP
    truth-logs/                 # epistemic verification results
    archive/                    # completed WPs (terminal, no modification)
    reference/                  # TPMN-SKILL-STANDARD.md, TPMN-LIFECYCLE-GUIDE.md
    external-skills/            # archived skills (moved by /skill-to-kg)
    gem2-core-skills/           # local copy of 12 lifecycle skills
  .claude/
    skills/{slug}/SKILL.md      # project-specific extracted skills
  CLAUDE.md                     # behavioral rules
  .gitignore

Global (cross-project):
  ~/.claude/skills/             # 12 core TPMN lifecycle skills
  ~/.gem-squared/
    market-skills/              # community CONTRACT references

TPMN Quick Reference

| Symbol | Meaning | |--------|---------| | A | Input state | | B | Output state (always state, never action) | | F | Transform (A → B) | | P | Precondition | | 𝕊 ℕ ℝ 𝔹 | Types: string, natural, real, boolean | | Seq(T) | Sequence | | T? | Optional | | ⊤ / ⊥ | Top (true) / Bottom (null/absent) | | ∧ / ∨ / ¬ | And / Or / Not | | ≜ | Defined as | | ⊢ / ⊨ / ⊬ | Grounded / Inferred / Extrapolated |

Full spec: .gem-squared/reference/TPMN-SKILL-STANDARD.md + .gem-squared/reference/TPMN-LIFECYCLE-GUIDE.md

Layers

| Layer | What | Requires | |-------|------|----------| | L0 | git + .gem-squared/ files. Always works. | Nothing | | L1 | GEM² Studio MCP. Semantic search, session recovery, knowledge graph, web UI. | gem2-studio | | L2 | GEM² Epistemic Studio. Truth scoring, multi-provider verification. | gem2-epistemic-gateway |

Skills fall back to L0 automatically when L1/L2 are unavailable. No configuration needed.

Uninstall

npx @gem_squared/tpmn-skill-install uninstall

Removes global skills (~/.claude/skills/) and market skills (~/.gem-squared/market-skills/) added by this installer. Preserves all project files and your existing skills.

Want More?

GEM² Studio adds L1 capabilities:

• Semantic pattern search across projects
• Session recovery (pick up where you left off)
• Knowledge graph for proven contracts
• Cross-project learning (reuse patterns)
• Web UI with terminal, task board, and AI pilot
• MCP server for deep Claude Code integration

Learn more: github.com/gem-squared/gem2-studio

License

• Code and skills (bin/, skills/, templates/): MIT
• Specification documents (spec/): CC-BY-4.0

GEM².AI — gemsquared.ai