Limitations on Skill Features in Knowledge Work Plugins: Architectural Constraints and Safety Rules

Skills in the anthropics/knowledge-work-plugins repository face no domain-based restrictions—any deterministic business workflow can become a skill provided it declares metadata in front-matter, specifies connector compatibility, and gates mutating operations behind explicit owner approval.

The anthropics/knowledge-work-plugins repository enables teams to convert business capabilities into declarative, natural-language-triggered workflows called Skills. While there are effectively no limits on the business domain or feature type that can be defined as a skill, the Instagit platform enforces strict architectural and safety constraints to ensure secure, predictable execution. These limitations focus on metadata structure, connector dependencies, and approval workflows rather than restricting the underlying business logic.

Architectural Constraints on Skill Definitions

Mandatory Front-Matter Metadata

Every skill must declare its identity and requirements in a YAML front-matter block at the top of its SKILL.md file. According to the ticket-deflector implementation in small-business/skills/ticket-deflector/SKILL.md, this block must include the skill name, description, and compatibility fields. Without this declarative metadata, the runtime cannot discover, index, or surface the skill to users, making the front-matter schema a non-negotiable structural limitation.

Connector Compatibility Requirements

Skills must explicitly enumerate required and optional third-party connectors. The ticket-deflector skill specifies compatibility: "Requires PayPal, HubSpot, Mail. Optional: Intercom, Square." in its front-matter, ensuring the runtime only invokes the skill when necessary services are available. If required connectors are missing, the skill will not execute; if optional connectors are absent, the skill must gracefully degrade or note the gap.

Declarative Trigger Phrases

The dispatcher requires unambiguous natural-language triggers to route requests correctly. Each skill must include declarative trigger phrases such as "Trigger this skill whenever the user mentions..." as documented in the tax-season-organizer skill. Ambiguous or conditional triggers violate the platform's routing architecture and will prevent proper skill invocation.

Safety Boundaries and Execution Limits

Approval Gates for Mutating Operations

Any skill performing destructive or irreversible operations—such as issuing refunds or modifying records—must implement explicit approval steps. The ticket-deflector SKILL.md documents this pattern in steps 5-7: "Approval gate — owner reviews the draft" and "Approval gate — refund issuance" with confirmation prompts like "Issue refund of $[amount] to [customer name] ([email]) for transaction [ID]? Reply Y to proceed." This enforces the global safety rule: never act without explicit owner confirmation.

Read-Only Defaults

Skills operate as read-only by default unless explicitly configured otherwise. The cash-flow-snapshot skill in small-business/skills/cash-flow-snapshot/SKILL.md is marked "read-only" in its compatibility string, allowing automatic execution without user intervention. Write-back capabilities require explicit opt-in and additional approval gates, preventing accidental data mutations.

Secret Isolation and Credential Handling

The platform enforces a strict no-secret-leakage policy defined in the top-level opencode.json file. API keys and credentials are never injected into skill code; they are provided exclusively by the connector runtime at execution time. Skills cannot hardcode secrets or access credentials outside the approved connector framework.

What Qualifies as a Valid Skill Feature

Any deterministic workflow—whether "draft a contract," "run single-cell RNA-seq QC," or "generate a tax estimate"—can become a skill. The tax-season-organizer skill in small-business/skills/tax-season-organizer/reference/gotchas.md demonstrates that complex business logic integrates seamlessly with the required schema. The only hard limits are architectural: the skill must follow the front-matter schema, declare connector dependencies, and gate mutations behind approval.

Implementation Examples

Minimal Skill Front-Matter

---
name: tax-season-organizer
description: |
  Generates a quarterly-tax estimate from revenue, expenses and SE-tax.
compatibility: "Requires QuickBooks MCP, optional CSV fallback."
---

This block lives at the top of the SKILL.md file in small-business/skills/tax-season-organizer/reference/gotchas.md.

Approval Gate Pattern

5. **Approval gate — owner reviews the draft.**  
6. **Approval gate — refund issuance.**  
   > "Issue refund of $[amount] to [customer name] ([email]) for transaction [ID]? Reply Y to proceed."

These steps from small-business/skills/ticket-deflector/SKILL.md enforce the explicit confirmation requirement.

Compatibility Declaration with Fallbacks

compatibility: "Requires PayPal, HubSpot, Mail. Optional: Intercom, Square."

The runtime checks for required connectors before invocation; missing optional connectors trigger fallback behavior rather than execution failure.

Summary

• No domain restrictions exist: Any business capability expressed as deterministic steps can become a skill.
• Front-matter schema is mandatory: Skills must declare name, description, and compatibility in YAML front-matter within SKILL.md.
• Connectors must be explicit: Required and optional third-party services must be listed in the compatibility field.
• Mutations require approval: Write operations must be gated behind explicit owner confirmation prompts.
• Secrets are isolated: Credentials are provided by the connector runtime, never hardcoded in skill logic.

Frequently Asked Questions

Can any business logic be turned into a skill?

Yes, provided the logic can be expressed as a deterministic workflow of data fetch, transformation, and optional write-back. The business domain—whether tax calculation, laboratory QC, or contract drafting—does not limit eligibility. The workflow must only adhere to the front-matter schema and safety rules enforced by opencode.json.

Do skills support destructive operations like refunds?

Yes, but only with explicit approval gates. Skills performing irreversible actions, such as the ticket-deflector skill issuing PayPal refunds, must implement step-by-step owner confirmation. The pattern requires presenting the action details and requiring an explicit "Y" response or equivalent confirmation before execution.

What happens if a required connector is missing?

The runtime checks the compatibility field before invoking a skill. If a required connector (e.g., QuickBooks, PayPal) is unavailable, the skill will not execute. For optional connectors listed in the compatibility string, the skill must implement fallback logic or note the missing data gap without failing.

Are there limits on the programming language used?

The repository does not specify programming language limitations in the skill definition itself. However, all external actions must route through the connector runtime, and secrets must never be embedded in code. The logic is typically defined in the SKILL.md workflow description and interpreted by the Instagit platform rather than executed as arbitrary code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}