Improve/skill review optimization

.github/workflows/skill-preview.yml

@@ -0,0 +1,13 @@
+name: Skill Review
+on:
+  pull_request:
+    paths: ['**/SKILL.md']
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review@22e928dd837202b2b1d1397e0114c92e0fae5ead # main

skills/enterprise-readiness-protocol/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: enterprise-readiness-protocol
-description: >
-  The Enterprise Readiness Protocol specification — the open standard
-  format for declaring what vendors need from enterprise environments.
-  Includes canonical dependency types for deterministic matching.
-  Loaded automatically by interf-draft and interf-preview.
+description: "Defines the interf.yaml schema for enterprise readiness contracts — validation rules, field specifications, and canonical dependency types. Provides spec.md for schema reference and examples.md for realistic contract templates. Loaded automatically by interf-draft and interf-preview when drafting or previewing enterprise rollout contracts."
 user-invocable: false
 ---
 
@@ -14,18 +10,29 @@ An open standard for declaring what vendors need from enterprise environments be
 
 ## Contract Format
 
-See [spec.md](./spec.md) for the `interf.yaml` schema:
-- `requirements` — what you need, with `what` + `ready` acceptance criteria
-- `optional` — nice-to-have dependencies
-- `canonical` — optional reference to a canonical dependency type
+Every contract is an `interf.yaml` file with `what` + `ready` pairs:
 
-## Examples
+```yaml
+name: acme-crm-automation
+version: 0.1.0
+description: Automates CRM data entry
 
-See [examples.md](./examples.md) for realistic contracts across different rollout types.
+requirements:
+  - what: Read/write access to your CRM (contacts and opportunities)
+    ready: We can create a contact and read an opportunity via API from staging
+    canonical: integration.crm.api
+
+optional:
+  - what: Webhook endpoint for real-time CRM updates
+    ready: We receive a test webhook payload within 5 seconds of a CRM update
+    canonical: integration.webhook.outbound
+```
+
+See [spec.md](./spec.md) for the full schema and validation rules. See [examples.md](./examples.md) for realistic contracts across different rollout types.
 
 ## How It Works
 
-1. **Declare** — Vendor declares `interf.yaml` with every enterprise dependency.
+1. **Draft** — Vendor creates `interf.yaml` listing every enterprise dependency with `what` + `ready` criteria. Run `npx interf validate` to check schema and canonical type IDs.
 2. **Deliver** — Contract is published to the Interf registry or sent directly to enterprise.
 3. **Resolve** — Enterprise works through each requirement, audited against the `ready` criteria.
-4. **Verify** — All requirements resolved. Rollout can proceed.
+4. **Verify** — All requirements resolved and acceptance criteria met. Rollout can proceed.

skills/interf-draft/SKILL.md

@@ -1,33 +1,26 @@
 ---
 name: interf-draft
-description: >
-  Draft an interf.yaml readiness contract by scanning the codebase for
-  enterprise dependencies, or define them manually. Use when you need to
-  specify what you need from enterprise before rollout.
+description: "Draft an interf.yaml readiness contract by scanning the codebase for enterprise dependencies — API endpoints, auth providers, infrastructure requirements, and stakeholder needs — or define them manually. Use when creating rollout prerequisites, pre-launch checklists, or specifying what a vendor needs from enterprise before deployment."
 ---
 
-# Declare Readiness Contract
+# Draft Readiness Contract
 
-Extract or define an `interf.yaml` readiness contract declaring what you need from enterprise environments.
+Extract or define an `interf.yaml` readiness contract declaring what the project needs from enterprise environments.
 
 ## Before You Start
 
 **Load the canonical dependency types first.** Read [the protocol skill's canonical-dependencies/index.md](../protocol/canonical-dependencies/index.md) to understand what canonical types are available. Use the correct canonical IDs — do not invent shorthand.
 
 ## Step 1: Analyze the Project
 
-- What does this project do and who are the enterprise users?
-- What external systems does it connect to?
-- What data access is needed?
-- What authentication/authorization is required?
-- Who needs to be involved on the enterprise side?
-- What reviews or approvals are typical?
+Scan the codebase for enterprise dependencies:
 
-Look at:
-- Configuration files (environment variables, API endpoints, auth config)
-- Integration code (API clients, database connections, webhook handlers)
-- Documentation (architecture docs, setup guides, runbooks)
-- Deployment config (infrastructure requirements, network rules)
+- **Configuration files** — environment variables, API endpoints, auth config
+- **Integration code** — API clients, database connections, webhook handlers
+- **Deployment config** — infrastructure requirements, network rules, environment setup
+- **Documentation** — architecture docs, setup guides referencing external systems
+
+Identify what external systems, data access, authentication, stakeholders, and approval processes the project depends on.
 
 ## Step 2: Map to Canonical Types
 
@@ -74,7 +67,7 @@ optional:
 5. **Include stakeholder dependencies.** If someone needs to be involved (data team, security team), that's a requirement too.
 6. **Include process dependencies.** Security review, compliance review, training — these are the blockers FDEs hate discovering mid-flight.
 
-## Step 4: Validate (Optional)
+## Step 4: Validate
 
 After writing `interf.yaml`, validate it against the protocol schema and canonical types:
 
@@ -87,4 +80,4 @@ This checks:
 - Canonical type IDs against the latest known types
 - Suggests corrections for shorthand or hallucinated IDs (e.g. `sso` → `auth.sso.saml`)
 
-If the CLI is not installed, suggest the user run `npx interf validate` — it auto-installs and validates in one step.
+If validation fails, fix the flagged issues and re-run until the contract passes. If the CLI is not installed, `npx interf validate` auto-installs and validates in one step.

skills/interf-preview/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: interf-preview
-description: >
-  Preview enterprise rollout against a company profile. Produces
-  resolution timelines, identifies stakeholders, and surfaces risks.
-  Use when you want to understand what rollout looks like at a specific enterprise.
+description: "Preview enterprise rollout against a company profile — produces resolution timelines, identifies stakeholders, maps dependency chains, and surfaces risks. Use when generating a deployment plan, implementation preview, or go-to-market readiness assessment for a specific enterprise customer."
 ---
 
 # Preview Enterprise Rollout
@@ -14,6 +11,7 @@ Generate a rollout preview for a specific enterprise based on an `interf.yaml` r
 
 1. **Load the contract.** Read the project's `interf.yaml`. If none exists, run the `interf-draft` skill first.
 2. **Load canonical types.** Read [canonical-dependencies/index.md](../protocol/canonical-dependencies/index.md) for dependency relationships, blockers, and sector patterns.
+3. **Verify inputs.** Confirm the contract has at least one requirement with `what` + `ready` fields. If any `canonical` IDs are present, verify they resolve against the canonical-dependencies reference.
 
 ## Step 1: Build Enterprise Profile
 
@@ -23,6 +21,8 @@ Research the target enterprise:
 - **Known systems** — Salesforce, SAP, Okta, etc. (from public info, job postings, tech stack databases)
 - **Regulatory environment** — HIPAA, PCI-DSS, SOX, GDPR, etc.
 
+Verify the profile covers all four dimensions before proceeding — gaps here cascade into inaccurate timelines.
+
 ## Step 2: Analyze Each Requirement
 
 For each requirement in the contract:
@@ -36,24 +36,32 @@ For each requirement in the contract:
    - **Risks** — what could go wrong (from key risks / common gotchas)
    - **Complexity** — from the canonical type's complexity field
 
+Flag any requirements where canonical types could not be resolved or where sector/system data is missing.
+
 ## Step 3: Build Resolution Timeline
 
 1. Order requirements by dependency chain (what blocks what)
 2. Identify the critical path (longest sequential chain)
 3. Group parallel work streams
 4. Flag high-risk items
 
+Example dependency chain: `auth.sso.saml` → `integration.crm.api` → `data.historical-export` (SSO must be live before CRM API access, which must be live before historical data export can begin).
+
 ## Step 4: Present the Preview
 
 For each requirement:
-- Resolution approach and steps
-- Stakeholders involved
-- Estimated complexity (low / medium / high)
-- Risks and mitigations
-- What it's blocked by
+
+| Field | Description |
+|-------|-------------|
+| **Requirement** | The `what` from the contract |
+| **Approach** | Resolution steps for this enterprise |
+| **Stakeholders** | Who needs to be involved |
+| **Complexity** | Low / Medium / High |
+| **Risks** | What could go wrong and mitigations |
+| **Blocked by** | Other requirements that must resolve first |
 
 Summary:
-- **Critical path** with ordered dependencies
-- **Parallel work streams** that can run concurrently
-- **Top risks** across the rollout
-- **Key stakeholders** and their involvement
+- **Critical path** — ordered dependency chain with the longest sequential resolution time
+- **Parallel work streams** — requirements that can be resolved concurrently
+- **Top risks** — highest-impact risks across the rollout with mitigations
+- **Key stakeholders** — all involved parties and their requirements