🏛️ TidyFactor Skill Architect v2.7.1

The Canonical Governance Engine & Architecture Specification for AI Coding Agent Skills.
Enforces the 15 Structural Rules and the Universal 6-Axis Periodic Review Protocol of TidyFactor Skills across Google Antigravity, Claude Code, Cursor, OpenAI Codex, and Windsurf.

Install and register tidyfactor-skill-architect into your active coding environment in seconds:

# Option A: Install via official TidyFactor Ecosystem CLI (Recommended)
npx @tidyfactor/cli add skill-architect

# Option B: Install via Open Agent Skills multi-agent standard (skills.sh)
npx skills add tidyfactor/skill-architect

# Option C: Direct standalone runner (zero global dependencies)
npx @tidyfactor/skill-architect@latest

• Overview & Philosophy
  • The Problem It Solves
  • The TidyFactor Solution
  • Progressive Disclosure Architecture
• Commands & Operational Workflows
  • Summary of Commands
  • 1. init — Scaffold a New Skill
  • 2. audit — Audit & Score an Existing Skill
  • 3. review — Universal 6-Axis Periodic Review Protocol
  • 4. test — Generate Test Scenarios
  • 5. grow — Evaluate Architecture Growth
• Universal 6-Axis Periodic Skill Review Protocol
  • The 6 Core Evaluation Axes
  • 100-Point Audit Rubric & Grading Thresholds
• The 15 Structural Rules of TidyFactor Skills
• The Contextual Decision Layer (CDL v2.0)
  • 4-Phase Arbitration Pattern
  • Execution Modes: Mode A (Modal Wizard) vs Mode B (Debate Mode)
• Tooling & Integrity Validation Suite
  • 13-Point Automated Validation Matrix
• Cross-Agent Distribution & Synchronization
• Installation & Detailed Guide
  • CLI & Package Options
  • Manual Agent Registration
• License & Credits

tidyfactor-skill-architect is the foundational governance layer that establishes standard operating procedures for creating, auditing, expanding, packaging, and maintaining AI Coding Agent Skills across diverse developer ecosystems.

Traditional AI coding skills frequently degrade due to four systemic anti-patterns:

1. Context Window Pollution: Giant monolithic prompt files dump thousands of tokens into the context window upon session boot, degrading reasoning depth.
2. Execution Hallucinations: Ambiguous instructional text causes models to "guess" parameters instead of traversing deterministic, schema-validated execution graphs.
3. Multi-Agent Behavioral Drift: Divergent behaviors between Antigravity, Claude Code, Cursor, Codex, and Windsurf due to vendor-specific lock-in.
4. Syntax & Frontmatter Failures: Unquoted strings or invalid YAML frontmatter silently break IDE autocomplete and slash (/) command discovery.

A TidyFactor skill is engineered not as an instructional prompt, but as a high-speed deterministic router that applies Progressive Disclosure: loading only the minimal necessary context at the exact moment it is required.

┌─────────────────────────────────────────────────────────────────────────┐
│                      Session Discovery Layer                            │
│           SKILL.md Frontmatter (name + description ≤ 1024 chars)        │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ (Trigger Matched)
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      Dispatcher Layer (Router)                          │
│            SKILL.md (~350 tokens, Anti-triggers, Tool Scope)            │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ (Intent Identified)
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                     Command Layer (Router Link)                         │
│                  references/commands/<command>.md                       │
└──────────────────┬───────────────────────────────────┬──────────────────┘
                   │ (Loads Workflow)                  │ (Injects Memory)
                   ▼                                   ▼
┌─────────────────────────────────────┐ ┌─────────────────────────────────┐
│           Workflow Layer            │ │          Memory Layer           │
│       Ordered Execution Steps       │ │   Pure Technical Constraints    │
│       + Validation Checklist        │ │   Schemas, Rules, Data Tables   │
└─────────────────────────────────────┘ └─────────────────────────────────┘

• User Intent: Create a new production-ready AI skill from scratch following TidyFactor invariants.
• Workflow Loaded: references/workflows/create-skill.md + references/memory/spec.md + references/memory/growth-rule.md + assets/skill-md-skeleton.md.
• Delivered Output: Complete directory scaffold, compliant SKILL.md dispatcher (~350 tokens), first workflow with a ## Validation checklist, and metadata files (package.json, .tidyfactor, brand.yaml).

• User Intent: Verify an existing skill's structural integrity against the 15 Structural Rules.
• Workflow Loaded: references/workflows/audit-skill.md + references/memory/spec.md.
• Delivered Output: Quantitative compliance scorecard (Score: X/15), enumerated rule violations, and mechanical file-level diffs.

• User Intent: Conduct scheduled quarterly or pre-release maintenance reviews across all 6 engineering dimensions.
• Workflow Loaded: references/workflows/periodic-review.md + references/memory/periodic-review-matrix.md.
• Delivered Output: Standardized 100-point 6-Axis scorecard, orphan asset purge, stale date refresh, and deduplication report.

• User Intent: Generate black-box evaluation prompts to validate skill triggering, execution paths, and negative-case rejection.
• Workflow Loaded: references/workflows/test-skill.md + references/memory/spec.md.
• Delivered Output: Minimum 3 test cases added to tests/scenarios.md covering Happy Path, Complex/Edge Case, and Anti-Trigger Rejection.

• User Intent: Decide whether new capabilities warrant adding files, splitting workflows, or creating a separate skill.
• Workflow Loaded: references/memory/growth-rule.md.
• Delivered Output: Mathematical evaluation based on line counts ($\ge 400$ lines), branch variants, and contextual triggers (SPLIT, EXPAND, or REJECT).

Introduced in v2.7.0, the 6-Axis Periodic Skill Review Protocol provides a repeatable, objective maintenance engine to prevent architectural rot, stale knowledge, and asset bloat over time.

   ┌────────────────────────────────────────────────────────┐
   │       Universal 6-Axis Periodic Review Engine          │
   └───────┬────────────┬────────────┬────────────┬─────────┘
           │            │            │            │
    ┌──────▼─────┐┌─────▼──────┐┌────▼───────┐┌───▼────────┐
    │   Axis 1   ││   Axis 2   ││   Axis 3   ││   Axis 4   │
    │  Commands  ││  Workflows ││   Memory   ││   Tooling  │
    └────────────┘└────────────┘└────────────┘└────────────┘
                        │                     │
                 ┌──────▼──────┐       ┌──────▼──────┐
                 │   Axis 5    │       │   Axis 6    │
                 │ Governance  │       │ Asset Clean │
                 └─────────────┘       └─────────────┘

1. Axis 1: Commands & Context-Aware Prompts (20 pts)
   • Manifest synchronization between SKILL.md table and references/commands/.
   • Single-router dispatch discipline; zero multi-command sprawl.
2. Axis 2: Workflows & Single Outcome Checklists (20 pts)
   • Exactly one tangible outcome per workflow file.
   • Mandatory, non-empty ## Validation checklist concluding every workflow.
3. Axis 3: Operational Memory Purity & YAML Primacy (15 pts)
   • Zero marketing copy, fluff, or ideological text inside memory files.
   • Rule 15 YAML Primacy (brand.yaml, briefs) for 35–50% token reduction.
   • Active freshness timestamps (<!-- last-verified: YYYY-MM-DD --> $\le 180$ days).
4. Axis 4: Tooling, AST Scrapers & Protocol Integration (15 pts)
   • Zero Runtime Crash guarantee via deterministic Node/Python scripts in tools/.
   • Safe MCP boundary declarations with fail-open fallback logic.
5. Axis 5: Governance, Markdown Linting & Tone of Voice (15 pts)
   • Atomic SemVer synchronization across all metadata files.
   • Single Source of Truth adherence and secret scanning passes.
   • Direct, technical tone free of conversational bot preambles.
6. Axis 6: Assets & Folder Structure Hygiene (15 pts)
   • SHA-256 duplicate image and media elimination.
   • Zero orphaned or unreferenced assets in assets/.
   • WebP format optimization for web previews.

Every skill in the TidyFactor ecosystem strictly complies with the 15 Structural Rules:

For complex skills where execution depends on interdependent architectural choices, the Skill Architect codifies the CDL Pattern:

1. Active Context Synthesis: Scans workspace files (e.g. package.json, composer.json, existing configs) and persistent Knowledge Items (KIs) to identify already settled decisions.
2. Pre-flight Brief & Local Cache (brief command): Gathers missing parameters and persists them to .tidyfactor/<skill>-brief.md as the local Single Source of Truth.
3. Single-Round Interactive Arbitration:
   • Mode A (Smart Modal Wizard): Never outputs questionnaires as plain chat text. Invokes the IDE's native interactive modal tool (ask_question) in 1 structured round (max 3 questions).
   • Mode B (Debate Mode): Evaluates complex trade-offs with architectural recommendations before final code emission.
4. Decision Alignment Axis (D): Evaluates generated code against Axis 7 (D - Decision Alignment) during pre-emit self-critique (/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */).

The skill includes a deterministic verification engine that ensures strict compliance before release:

# Run the 13-point automated integrity validator
python tools/validate_skill.py

When compiling with node tools/build-skill.js, the builder automatically packages the distribution bundle and synchronizes across all registered target environments:

Skills-LAB/tidyfactor-skill-architect/ (Single Source of Truth - SSOT)
  ├── 📦 dist/tidyfactor-skill-architect.skill (Latest Claude Archive)
  ├── 📦 dist/tidyfactor-skill-architect-v2.7.1.skill (Versioned Archive)
  ├── 🔁 .agents/skills/tidyfactor-skill-architect/ (Local Workspace Agent)
  ├── 🔁 ~/.gemini/config/skills/tidyfactor-skill-architect/ (Global Antigravity / Gemini)
  └── 🔁 /mnt/skills/user/tidyfactor-skill-architect/ (Claude / Unix Runtime)

Choose your preferred installation method:

Install directly into your active workspace using the official CLI:

npx @tidyfactor/cli add skill-architect

Or if you have the CLI installed globally (npm i -g @tidyfactor/cli):

tidyfactor add skill-architect

Install using the universal multi-agent standard across Cursor, Antigravity, Claude Code, Windsurf, Trae, and Codex:

npx skills add tidyfactor/skill-architect

Run the dedicated skill installer directly with automatic cache invalidation:

npx @tidyfactor/skill-architect@latest

You can also manually clone or copy the skill directory into your agent's customization root:

# Google Antigravity & Gemini IDE (Global Customization Root)
cp -r tidyfactor-skill-architect ~/.gemini/config/skills/

# Local Project Agent Wrapper (Workspace Root)
cp -r tidyfactor-skill-architect .agents/skills/

• License: Apache-2.0
• Engineered by: TidyFactor Ecosystem & Alwkala Digital Agency
• Official Inquiries: hello@tidyfactor.com | +201016656899
• Location: Cairo, Egypt