From 3e9d906effbe6d29582483ae8837a38844957bb7 Mon Sep 17 00:00:00 2001 From: Yogi Date: Mon, 13 Apr 2026 14:48:25 +0530 Subject: [PATCH 1/2] feat: improve skill scores for enterprise-readiness-protocol MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @gedossman 👋 I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | enterprise-readiness-protocol | 45% | 76% | +31% | | interf-draft | 79% | 88% | +9% | | interf-preview | 74% | 88% | +14% | **enterprise-readiness-protocol** (+31%) - Rewrote description with concrete actions (defines schema, validation rules, field specs) instead of abstract "open standard" language - Added inline YAML example so the contract format is immediately visible without reading spec.md - Added `npx interf validate` command to the Draft step for actionability - Made workflow steps more concrete (Draft step now mentions validation) **interf-draft** (+9%) - Expanded description with specific dependency types scanned (API endpoints, auth providers, infrastructure, stakeholders) and natural trigger terms (rollout prerequisites, pre-launch checklists) - Tightened Step 1 from rhetorical questions to a focused scan checklist - Made validation step non-optional with a fix-and-rerun feedback loop - Changed heading from "Declare" to "Draft" to match the skill name **interf-preview** (+14%) - Added natural trigger terms to description (deployment plan, implementation preview, go-to-market readiness assessment) - Added input verification step in "Before You Start" (contract has requirements, canonical IDs resolve) - Added validation checkpoint after building enterprise profile - Added example dependency chain to make Step 3 concrete - Added structured output table format in Step 4 for consistent deliverables **All skills** - Converted description frontmatter from block scalar (>) to quoted string format Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at this Tessl guide (https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - @yogesh-tessl (https://github.com/yogesh-tessl) - if you hit any snags. Thanks in advance 🙏 --- skills/enterprise-readiness-protocol/SKILL.md | 33 +++++++++++------- skills/interf-draft/SKILL.md | 31 +++++++---------- skills/interf-preview/SKILL.md | 34 ++++++++++++------- 3 files changed, 53 insertions(+), 45 deletions(-) diff --git a/skills/enterprise-readiness-protocol/SKILL.md b/skills/enterprise-readiness-protocol/SKILL.md index 4622a67..f819227 100644 --- a/skills/enterprise-readiness-protocol/SKILL.md +++ b/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. diff --git a/skills/interf-draft/SKILL.md b/skills/interf-draft/SKILL.md index bb0c992..e331de2 100644 --- a/skills/interf-draft/SKILL.md +++ b/skills/interf-draft/SKILL.md @@ -1,14 +1,11 @@ --- 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 @@ -16,18 +13,14 @@ Extract or define an `interf.yaml` readiness contract declaring what you need fr ## 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. diff --git a/skills/interf-preview/SKILL.md b/skills/interf-preview/SKILL.md index 01f8e3b..7c91e60 100644 --- a/skills/interf-preview/SKILL.md +++ b/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,6 +36,8 @@ 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) @@ -43,17 +45,23 @@ For each requirement in the contract: 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 From 03c7af40c8b0633cd4ea415af20dee1f13cf6695 Mon Sep 17 00:00:00 2001 From: Yogi Date: Mon, 13 Apr 2026 18:28:20 +0530 Subject: [PATCH 2/2] ci: add skill-review GitHub Action for automated skill review on PRs --- .github/workflows/skill-preview.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/workflows/skill-preview.yml diff --git a/.github/workflows/skill-preview.yml b/.github/workflows/skill-preview.yml new file mode 100644 index 0000000..60c71a4 --- /dev/null +++ b/.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 \ No newline at end of file