se-skills

v1.0.10

Published

13 days ago

Software engineering directives and AI skills suite for autonomous coding agents (Antigravity, Claude Code, Cursor, Hermes, Windsurf, Cline, Copilot, OMP, OpenCode, Kiro).

Software Engineering Directives for AI Coding Agents (`se-skills`)

se-skills is a zero-dependency CLI engineering suite that injects formal architectural boundaries, data integrity invariants, cybersecurity defense protocols, and deterministic testing standards directly into AI coding agent workspaces (Google Antigravity, Claude Code, Cursor, GitHub Copilot, Cline/Windsurf, OMP, OpenCode, and Kiro). Explore the interactive catalog and benchmarks at se-skills.vercel.app.

1. The Core Problem: AI Code Slop & Cognitive Laziness

Large Language Models (LLMs) are pre-trained on hundreds of millions of public repositories, the statistical majority of which are student tutorials, beginner homework, and unmaintained hobby projects. Left unconstrained, coding assistants default to this probabilistic median, generating code that is superficially functional but architecturally catastrophic:

Missing Transactional Invariants: Mutating multiple database records via non-atomic operations, causing unrecoverable data corruption upon network drops.
Silent Concurrency Failures: Lack of row-level pessimistic locks (FOR UPDATE) or optimistic lock versions, causing lost updates and race condition exploits.
Accidental Asymptotic Disasters: Calling .find() or .filter() inside loops, creating $O(n^2)$ latency bottlenecks in memory, or triggering $N+1$ queries in databases.
Fragile Frontend Architecture: Proliferating 20+ boolean flags (hasHeader, isSmall, showBorder) instead of compound components, accompanied by arbitrary single-word colors and visual cages (AI slop).
Security Vulnerabilities: String-concatenated SQL queries, exposed stack traces, and unauthenticated object-level operations (BOLA / IDOR).

se-skills establishes an unyielding Hierarchy of Engineering Rigor that constrains your AI agent to produce provable, enterprise-grade software.

2. Architecture & System Topology

se-skills acts as an invariant fence between your developer prompt and the agent's code generator:

┌─────────────────────────────────────────────────────────────────────────────┐
│                            DEVELOPER INSTRUCTION                            │
│           "Implement a wallet balance deduction and payment dispatch"       │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    SE-SKILLS INVARIANT GOVERNANCE LAYER                     │
├──────────────────────────────────────┬──────────────────────────────────────┤
│ 1. Master Constitution               │ Universal Invariants (Zero-Tolerance)│
│    (.agents/AGENTS.md)               │ Purity, Zero-Trust, Algorithmic O(1) │
├──────────────────────────────────────┼──────────────────────────────────────┤
│ 2. Domain Deep Directives            │ Financial Double-Entry, PCI-DSS v4.0 │
│    (references/domains/fintech.md)   │ Zero Float Math, Immutable Ledger    │
├──────────────────────────────────────┼──────────────────────────────────────┤
│ 3. Specialized Modular Skills        │ ACID Isolation, Expand-Contract      │
│    (skills/se-data-integrity/)       │ RFC 9110 Idempotency, Row Locks      │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      AI CODING AGENT WORKSPACE ENGINE                       │
│           (Google Antigravity | Claude Code | Cursor | Copilot)             │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          VERIFIED ENTERPRISE CODE                           │
│     Atomic db.transaction() | Row-Level Lock | Double-Entry Journal Entries  │
└─────────────────────────────────────────────────────────────────────────────┘

3. Proof of Rigor: Architectural Benchmarks

3.1. Backend Benchmark: Financial Funds Transfer

Unchecked Generative AI Baseline (Default Output)

// Critical Defects: Missing transaction, race condition, float precision loss
async function transferFunds(fromId: string, toId: string, amount: number) {
  const sender = await db.findUser(fromId);
  if (sender.balance < amount) {
    throw new Error("Insufficient balance");
  }

  // Crash here creates permanent money loss (sender deducted, receiver never credited)
  await db.updateBalance(fromId, sender.balance - amount);
  await db.updateBalance(toId, receiver.balance + amount);

  return { status: "ok" };
}

Enforced with `se-skills` Directives

// Enforced: ACID transaction, RFC 9110 idempotency, row-level locks, double-entry ledger
async function transferFunds(ctx: TransactionContext, cmd: TransferCommand): Promise<TransferResult> {
  return await db.transaction(async (trx) => {
    // 1. Assert idempotency key before any mutation
    await trx.assertIdempotency(cmd.idempotencyKey);

    // 2. Pessimistic row-level lock prevents race conditions
    const sender = await trx.lockUserForUpdate(cmd.fromId);
    if (sender.balanceMinor < cmd.amountMinor) {
      throw new InsufficientFundsError(cmd.fromId, cmd.amountMinor);
    }

    // 3. Double-entry immutable journal entry (Sum of debits must equal sum of credits)
    await trx.appendLedgerJournal([
      { accountId: cmd.fromId, debit: cmd.amountMinor },
      { accountId: cmd.toId, credit: cmd.amountMinor }
    ]);

    return { success: true, ref: cmd.idempotencyKey };
  });
}

3.2. Frontend Benchmark: UI Metric Component

Unchecked Generative AI Baseline (Boolean Soup & AI Slop)

// Flaws: Boolean prop proliferation, no tabular numerals, redundant useEffect, nested visual cage
export function MetricCard({ title, value, isSmall, isHighlighted, hasBorder, showTag }: any) {
  const [formatted, setFormatted] = useState('');
  useEffect(() => {
    setFormatted(new Intl.NumberFormat().format(value));
  }, [value]);

  return (
    <div className={`p-4 ${hasBorder ? 'border border-zinc-800' : ''} ${isHighlighted ? 'bg-zinc-900' : ''}`}>
      <span className="text-xs uppercase tracking-widest text-blue-400">METRIC</span>
      <h4 className="text-sm">{title}</h4>
      <p className="font-mono text-2xl">{formatted}</p>
    </div>
  );
}

Enforced with `se-frontend-web` Directives

// Enforced: Compound Component architecture, derived state, tabular-nums, W3C WCAG 2.2 AA
interface MetricProps {
  label: string;
  value: number;
  unit?: string;
  trend?: { direction: 'up' | 'down'; delta: string };
}

export function Metric({ label, value, unit, trend }: MetricProps) {
  // State derived during render (zero extra render cycles)
  const formattedValue = useMemo(() => new Intl.NumberFormat('en-US').format(value), [value]);

  return (
    <article className="surface-tier-1 p-6" aria-labelledby="metric-label">
      <h3 id="metric-label" className="text-secondary text-sm font-medium">{label}</h3>
      <div className="mt-2 flex items-baseline gap-1.5">
        <span className="text-primary text-3xl font-bold tabular-nums tracking-tight">
          {formattedValue}
        </span>
        {unit && <span className="text-muted text-sm">&nbsp;{unit}</span>}
      </div>
      {trend && (
        <span className="mt-2 inline-flex items-center text-xs text-muted" aria-label={`Trend ${trend.direction}`}>
          {trend.delta} vs baseline
        </span>
      )}
    </article>
  );
}

4. Dogfooding Proof: How `se-skills` Verifies Itself

We do not merely publish software engineering directives; this entire repository is built, audited, and strictly governed by its own skills:

| Quality Dimension | Standard / Metric | Implementation in se-skills | | :--- | :--- | :--- | | Functional Suitability | ISO/IEC 25010:2023 §6.1 | Deterministic CLI commands (init, status, route, adr, list) verified against matrix test suites. | | Performance Efficiency | Google Core Web Vitals | Zero runtime dependencies (0kB production overhead). Web client achieves P95 LCP $\le 0.4$s, INP $\le 16$ms, CLS $0.000$. | | Interaction Capability | W3C WCAG 2.2 Level AAA | High-contrast ratio $\ge 7:1$, semantic HTML5 landmarks, visible :focus-visible focus rings, full keyboard traversal. | | Security & Supply Chain | NIST SP 800-218 / SLSA | Zero third-party runtime dependencies. Zero telemetry, zero unauthenticated external network requests. | | Maintainability | Parnas Information Hiding | Strict separation of concerns between CLI primitives (bin/), templates (templates/), and client state (app.js). | | Visual Craft & Neuroaesthetics | Google 50ms / NN/g / Linear Craft | Processing fluency, halation defense (astigmatism ergonomics), surface elevation tiering, and strict elimination of AI slop (no navbar logo badges, no visual cages, no decorative dots). |

5. Quickstart Guide

Option A: Global IDE Installation (Active Across All Workspaces)

Install the binary globally and inject all 24 skills and the Master Constitution into your global IDE configuration (~/.gemini/config for Antigravity, ~/.claude for Claude Code, ~/.cursor for Cursor, ~/.hermes for Hermes, ~/.windsurf for Windsurf, ~/.clinerules for Cline, ~/.omp for OMP, ~/.config/opencode for OpenCode, ~/.kiro for Kiro):

npm install -g se-skills
se-skills init --global --yes

Result: Every workspace and conversation you start in your assistant immediately benefits from the Master Constitution and on-demand skills without needing to run init in every folder.

Option B: Local Repository Installation (Team & Git Tracking)

Scaffold standards into a specific project repository to commit agent configurations to version control:

cd your-project
se-skills init

Option C: Instant Execution via NPX (Zero Install)

Execute directly in any repository on demand without installing globally:

cd your-project
npx se-skills init

Supported Environments

Select your target AI environment during initialization:

Google Antigravity (Generates .agents/skills/ & .agents/AGENTS.md)
Claude Code (Generates .claude/skills/ & CLAUDE.md)
Cursor IDE (Generates .cursor/rules/*.mdc & .cursorrules)
Hermes Agent (Nous) (Generates .hermes/skills/ & AGENTS.md)
Windsurf (Cascade) (Generates .windsurf/rules/*.md & .windsurfrules)
Cline & Roo Code (Generates .clinerules/*.md & constitution.md)
GitHub Copilot (Generates .github/instructions/*.instructions.md & copilot-instructions.md)
OMP (Oh-My-Pi) (Generates .omp/skills/ & AGENTS.md)
OpenCode (Generates .opencode/skills/ & AGENTS.md)
Kiro (IDE & Agent) (Generates .kiro/steering/constitution.md & .kiro/skills/)
Universal Suite (Scaffolds all supported agent formats simultaneously)

Or pass non-interactive flags for automated CI/CD and scripted environments:

# Non-interactive Antigravity installation
se-skills init --target=agents --preset=web --yes

# Non-interactive Cursor installation
se-skills init --target=cursor --preset=ecommerce --yes

# Non-interactive Claude Code installation
se-skills init --target=claude --preset=fintech --yes

# Non-interactive Windsurf installation
se-skills init --target=windsurf --preset=saas --yes

# Non-interactive OMP installation
se-skills init --target=omp --preset=api --yes

# Non-interactive OpenCode installation
se-skills init --target=opencode --preset=web --yes

# Non-interactive Kiro installation
se-skills init --target=kiro --preset=fintech --yes

# Non-interactive Universal installation across all agent ecosystems
se-skills init --target=all --preset=all --yes

Step 3: Begin Pair Programming

Open your AI coding assistant as normal. The agent reads the installed constitution and automatically enforces architectural boundaries, data integrity invariants, and security rules without manual prompt reminders.

6. CLI Command Reference

All commands can be run directly via se-skills (when installed globally) or via npx se-skills (on-demand):

# Audit installation status in both current workspace and global IDE configs
se-skills status

# Evaluate project prompt and inspect recommended skills
se-skills route "Offline-first POS cash register with receipt printing"

# Create a numbered Architecture Decision Record (ISO 42010 compliant)
se-skills adr "Adopt PostgreSQL Row-Level Security for Multi-Tenancy"

# List all 24 skills and 18 domain specifications to terminal
se-skills list

7. Project Archetypes and Stack Presets

To eliminate decision fatigue when starting a new codebase, se-skills bundles verified skill sets for standard engineering archetypes:

You can also ask the CLI to suggest the exact stack for any arbitrary project description:

npx se-skills suggest "online grocery delivery with stripe checkout"

8. Skills Catalog

All skills adhere strictly to the open Agent Skills specification (SKILL.md):

9. Domain Specifications

Direct deep-domain guidance for high-consequence verticals located in references/domains/:

Fintech: Double-entry ledger journals, zero floating-point arithmetic, PCI-DSS v4.0 tokenization.
ERP: Multi-entity bounded contexts, FIFO inventory valuation, Segregation of Duties (SoD).
POS: Offline-first local SQLite WAL mode, hardware peripheral isolation, transactional receipts.
SaaS: Multi-tenant isolation via PostgreSQL Row-Level Security, noisy-neighbor mitigation.
E-Commerce: Two-phase soft inventory reservations, flash sale Redis Lua concurrency, Order FSM.
Healthcare: HIPAA compliance, HL7 FHIR resource models, DICOM medical imaging, Break-Glass emergency access.
Logistics & Supply Chain: Warehouse bin location lineage, fleet telematics, GeoJSON spatial constraints.
IoT & Embedded Telemetry: MQTT v5 / Sparkplug B protocols, CoAP UDP constraints, OPC UA industrial gateways.
Automotive: ISO 26262 ASIL A-D functional safety, AUTOSAR architecture, CAN bus message framing.
Aerospace & Avionics: DO-178C Level A determinism, ARINC 429/664 avionics buses, zero dead-code tolerance.
Media Streaming: HLS / MPEG-DASH chunking, WebRTC sub-second latency, adaptive bitrate encoding.
Gaming & Simulation: Client-side prediction, server reconciliation, tick rate budgets, GLI-19 RNG audit.
EdTech: IMS Global LTI 1.3, SCORM / xAPI telemetry, FERPA and COPPA student privacy safeguards.
Telecommunications: 3GPP 5G Service-Based Architecture (SBA), SIP protocol (RFC 3261), DPDK / eBPF bypass.
AdTech: OpenRTB 3.0 protocol, sub-50ms bid response SLA, click-fraud detection, Privacy Sandbox.
GovTech & Public Sector: eIDAS OpenID Connect federation, W3C WCAG 2.2 AAA accessibility, sovereign cloud isolation.
Web3 & Smart Contracts: Checks-effects-interactions pattern, reentrancy guards, flash-loan resistance.
AI & MLOps: Vector HNSW indexing, deterministic RAG retrieval, prompt injection defense fences.

10. Multi-Stack Idiomatic Execution

Every directive in se-skills provides precise, idiomatic implementations across major development stacks:

Rust: Pure domain modules; zero Tokio/SQLx primitives in domain core; safe ownership and explicit Result<T, DomainError>.
Go: Canonical internal/domain packaging; zero net/http or database primitives in core; explicit error returns.
TypeScript / Node.js: Strict runtime parsing via zod / valibot at system boundaries; pure domain entities without ORM decorators.
PHP (Laravel): Pure PHP classes in App\Domain; zero Eloquent inheritance in business core; immutable DTOs and FormRequests.
Python: Strict Pydantic v2 schemas; pure dataclasses; zero Django ORM or SQLAlchemy dependencies inside domain services.

11. Contributing & Community Guidelines

Contributions are welcome! Please read our guidelines before submitting pull requests: