From 0ab353475fc4a3c14dd56dd12bff167dcc70ae07 Mon Sep 17 00:00:00 2001 From: Mark Kats Date: Wed, 30 Sep 2026 12:33:27 +0300 Subject: [PATCH] feat(skills): reference contracts and invocation policies for airbase, auth, services and core skills --- .../skills/shd-airbase-manage/agents/openai.yaml | 2 +- .../shd-airbase-manage/references/mutation-contract.md | 8 ++++++++ .../skills/shd-airbase-query/agents/openai.yaml | 2 +- .../skills/shd-airbase-query/references/query-contract.md | 7 +++++++ .../skills/shd-auth-profile/agents/openai.yaml | 2 ++ .../shd-auth-profile/references/profile-contract.md | 7 +++++++ plugins/shd-mcp-plugin/skills/shd-routing/SKILL.md | 2 ++ .../shd-mcp-plugin/skills/shd-services/agents/openai.yaml | 2 ++ .../skills/shd-services/references/service-lifecycle.md | 7 +++++++ .../skills/shd-short-links/agents/openai.yaml | 2 ++ .../skills/shd-short-links/references/link-safety.md | 7 +++++++ .../skills/shd-system-base/agents/openai.yaml | 2 ++ .../shd-system-base/references/global-data-contract.md | 7 +++++++ 13 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 plugins/shd-mcp-plugin/skills/shd-airbase-manage/references/mutation-contract.md create mode 100644 plugins/shd-mcp-plugin/skills/shd-airbase-query/references/query-contract.md create mode 100644 plugins/shd-mcp-plugin/skills/shd-auth-profile/references/profile-contract.md create mode 100644 plugins/shd-mcp-plugin/skills/shd-services/references/service-lifecycle.md create mode 100644 plugins/shd-mcp-plugin/skills/shd-short-links/references/link-safety.md create mode 100644 plugins/shd-mcp-plugin/skills/shd-system-base/references/global-data-contract.md diff --git a/plugins/shd-mcp-plugin/skills/shd-airbase-manage/agents/openai.yaml b/plugins/shd-mcp-plugin/skills/shd-airbase-manage/agents/openai.yaml index b4dbf34..6ff6271 100644 --- a/plugins/shd-mcp-plugin/skills/shd-airbase-manage/agents/openai.yaml +++ b/plugins/shd-mcp-plugin/skills/shd-airbase-manage/agents/openai.yaml @@ -2,4 +2,4 @@ interface: display_name: "Управление AirBase" short_description: "Изменение схемы, записей и доступа AirBase" policy: - allow_implicit_invocation: true + allow_implicit_invocation: false \ No newline at end of file diff --git a/plugins/shd-mcp-plugin/skills/shd-airbase-manage/references/mutation-contract.md b/plugins/shd-mcp-plugin/skills/shd-airbase-manage/references/mutation-contract.md new file mode 100644 index 0000000..60b3d8d --- /dev/null +++ b/plugins/shd-mcp-plugin/skills/shd-airbase-manage/references/mutation-contract.md @@ -0,0 +1,8 @@ +# AirBase mutation contract + +- Resolve the user's selected project and exact Base before any mutation. Use the returned project and Base identifiers. +- Read the target table schema and current records first. Use field IDs, link targets and allowed values returned by SHD. +- Validate record values before create or update. Preview bulk create/upsert with `dry_run=true` and resolve every conflict before writing. +- Bulk cell updates have no dry-run. Review every record/field/value tuple before calling the mutation tool. +- Read the action schema and field usages before schema changes. Require explicit intent and confirmation for destructive changes, public access changes and external-table detachment. +- Keep AirBase project data separate from global System Base data. diff --git a/plugins/shd-mcp-plugin/skills/shd-airbase-query/agents/openai.yaml b/plugins/shd-mcp-plugin/skills/shd-airbase-query/agents/openai.yaml index 5aa792a..52bdb2b 100644 --- a/plugins/shd-mcp-plugin/skills/shd-airbase-query/agents/openai.yaml +++ b/plugins/shd-mcp-plugin/skills/shd-airbase-query/agents/openai.yaml @@ -2,4 +2,4 @@ interface: display_name: SHD AirBase queries short_description: Чтение записей и связей проекта policy: - allow_implicit_invocation: true + allow_implicit_invocation: false \ No newline at end of file diff --git a/plugins/shd-mcp-plugin/skills/shd-airbase-query/references/query-contract.md b/plugins/shd-mcp-plugin/skills/shd-airbase-query/references/query-contract.md new file mode 100644 index 0000000..ae194d3 --- /dev/null +++ b/plugins/shd-mcp-plugin/skills/shd-airbase-query/references/query-contract.md @@ -0,0 +1,7 @@ +# AirBase query contract + +- Search the resolved Base by concrete terms, then follow populated record links by their returned IDs. +- Relationship traversal is limited to four hops. Report `partial`, `truncated`, missing/failed reverse scans and depth-limit flags as limits on the result. +- A missing reverse scan or incomplete traversal is not proof that no matching relationship exists. +- Use live table and field IDs from returned schemas. Do not infer relationships from names, groups or expected wiring conventions. +- Return the shortest supported evidence chain and identify its first missing link. diff --git a/plugins/shd-mcp-plugin/skills/shd-auth-profile/agents/openai.yaml b/plugins/shd-mcp-plugin/skills/shd-auth-profile/agents/openai.yaml index 5dae84f..bb462f7 100644 --- a/plugins/shd-mcp-plugin/skills/shd-auth-profile/agents/openai.yaml +++ b/plugins/shd-mcp-plugin/skills/shd-auth-profile/agents/openai.yaml @@ -1,3 +1,5 @@ interface: display_name: SHD authenticated profile short_description: Inspect and update the authenticated profile +policy: + allow_implicit_invocation: false diff --git a/plugins/shd-mcp-plugin/skills/shd-auth-profile/references/profile-contract.md b/plugins/shd-mcp-plugin/skills/shd-auth-profile/references/profile-contract.md new file mode 100644 index 0000000..256dee1 --- /dev/null +++ b/plugins/shd-mcp-plugin/skills/shd-auth-profile/references/profile-contract.md @@ -0,0 +1,7 @@ +# Authenticated profile contract + +- Read the current-user resource before changing profile data and use the server's current concurrency values. +- Change only fields explicitly requested by the user and accepted by the profile tool schema. +- Treat email, password, sessions, recovery information, access flags, tokens and OIDC subjects as sensitive or out of scope. +- Unlink OIDC only on an explicit request and after the server confirms another sign-in method remains available. +- Preserve idempotency requirements and report the persisted server readback without exposing secrets. diff --git a/plugins/shd-mcp-plugin/skills/shd-routing/SKILL.md b/plugins/shd-mcp-plugin/skills/shd-routing/SKILL.md index a517d83..3c00004 100644 --- a/plugins/shd-mcp-plugin/skills/shd-routing/SKILL.md +++ b/plugins/shd-mcp-plugin/skills/shd-routing/SKILL.md @@ -17,6 +17,8 @@ readback. Do not invent fields, statuses, identifiers, routes or capabilities. - AirBase project-data questions and relationship lookups: use AirBase tools and `shd-airbase-query`. For duplicates, broken links or a broader data-quality audit, use `shd-airbase-audit`. +- AirBase schema, record, cell, field access, external table, public table + access or import changes: use `shd-airbase-manage`. - Tasks, task projects, task status or task dates: use Tasks tools and the `shd-task-workflow` workflow. - Project files and paths: use Files tools and the `shd-project-files` workflow. diff --git a/plugins/shd-mcp-plugin/skills/shd-services/agents/openai.yaml b/plugins/shd-mcp-plugin/skills/shd-services/agents/openai.yaml index 2c90aa5..4a2690c 100644 --- a/plugins/shd-mcp-plugin/skills/shd-services/agents/openai.yaml +++ b/plugins/shd-mcp-plugin/skills/shd-services/agents/openai.yaml @@ -1,3 +1,5 @@ interface: display_name: SHD services catalog short_description: Inspect and manage the SHD service catalog +policy: + allow_implicit_invocation: false diff --git a/plugins/shd-mcp-plugin/skills/shd-services/references/service-lifecycle.md b/plugins/shd-mcp-plugin/skills/shd-services/references/service-lifecycle.md new file mode 100644 index 0000000..170de54 --- /dev/null +++ b/plugins/shd-mcp-plugin/skills/shd-services/references/service-lifecycle.md @@ -0,0 +1,7 @@ +# Service lifecycle contract + +- Resolve the organization, service, version, site and publication from server results before acting. +- Read relevant service versions, usage and publication state before changing a lifecycle state. +- Keep draft, pending approval, published, failed, revoked, archived and restored states distinct. A version status alone does not prove publication succeeded. +- Editing a draft does not authorize publication. Publish, approve, archive, restore or revoke only the transition explicitly requested. +- Use fresh idempotency keys for publication/retry operations and verify the persisted publication result. Do not expose private credentials. diff --git a/plugins/shd-mcp-plugin/skills/shd-short-links/agents/openai.yaml b/plugins/shd-mcp-plugin/skills/shd-short-links/agents/openai.yaml index 1d84d7a..4743f53 100644 --- a/plugins/shd-mcp-plugin/skills/shd-short-links/agents/openai.yaml +++ b/plugins/shd-mcp-plugin/skills/shd-short-links/agents/openai.yaml @@ -1,3 +1,5 @@ interface: display_name: SHD short links short_description: Manage SHD short links and aliases +policy: + allow_implicit_invocation: false diff --git a/plugins/shd-mcp-plugin/skills/shd-short-links/references/link-safety.md b/plugins/shd-mcp-plugin/skills/shd-short-links/references/link-safety.md new file mode 100644 index 0000000..f797901 --- /dev/null +++ b/plugins/shd-mcp-plugin/skills/shd-short-links/references/link-safety.md @@ -0,0 +1,7 @@ +# Short-link safety contract + +- Resolve the exact link, owner, project, alias and status from current server data before updating it. +- Treat target URLs, public aliases, access flags and bearer tokens as sensitive. Never return bearer tokens or private redirect data. +- Change only requested fields and preserve the server's expected-version and idempotency contract. +- Rotation or revocation requires an explicit request, `confirm=true`, current concurrency data and a fresh idempotency key. +- Report the link ID, alias, affected fields, resulting status and server readback. diff --git a/plugins/shd-mcp-plugin/skills/shd-system-base/agents/openai.yaml b/plugins/shd-mcp-plugin/skills/shd-system-base/agents/openai.yaml index d657aff..9c2adb6 100644 --- a/plugins/shd-mcp-plugin/skills/shd-system-base/agents/openai.yaml +++ b/plugins/shd-mcp-plugin/skills/shd-system-base/agents/openai.yaml @@ -1,3 +1,5 @@ interface: display_name: SHD System Base short_description: Inspect allowlisted global SHD tables +policy: + allow_implicit_invocation: false diff --git a/plugins/shd-mcp-plugin/skills/shd-system-base/references/global-data-contract.md b/plugins/shd-mcp-plugin/skills/shd-system-base/references/global-data-contract.md new file mode 100644 index 0000000..94d0d00 --- /dev/null +++ b/plugins/shd-mcp-plugin/skills/shd-system-base/references/global-data-contract.md @@ -0,0 +1,7 @@ +# System Base contract + +- System Base is global and uses an allowlisted table set. Resolve table, record and field IDs from the server. +- Read the schema and current record/cell before an update. Preserve the current expected value and `record_version`. +- Update only the explicitly requested cell and use a fresh idempotency key. +- Deletion requires an explicit request, `confirm=true`, the current expected version and persisted readback. +- Keep System Base separate from project AirBase data; do not invent table names or broaden filters.