Organizational skills

Key takeaways

• A skill is guidance, not permission: every Action is still authorized by Contro1 when the agent calls it.
• Push a skill to the whole organization, a department, a person or one agent. The most specific assignment wins.
• Agents receive skills over MCP four ways at once, so it works in today's clients and in clients that speak the new MCP Skills extension.
• Published versions never change. Rollback publishes the old content as a new version, after showing who it moves.
• Every skill is scanned by NVIDIA SkillSpector, Cisco Skill Scanner and a Contro1 check. Nothing is blocked; a dangerous skill needs a named confirmation.

What a skill is

A skill is a SKILL.md file, with optional supporting files, that tells an agent how your organization wants something done: "refunds under $50 are approved, above that ask finance". It is the open Agent Skills format that Claude Code, Codex, Cursor and others already load, so a skill written in Contro1 is a normal skill.

A skill never grants anything. Whether an agent may send that email or issue that refund is decided by its grants and re-checked by Contro1 at the moment it acts. A skill that says "you may send from finance@" changes nothing about what the agent may do, and revoking a grant takes effect immediately even for an agent holding a day-old copy of its skills.

---
name: refund-policy
description: How we handle refund requests. Use for any refund or chargeback question.
---

# Refund policy

1. Refunds under $50: approve and reply with the standard template.
2. $50 and above: ask finance with create_approval_request before replying.
3. Never promise a refund date.

See references/templates.md for the reply templates.

How a skill reaches an agent

Contro1 works out, for each agent, which skills it has and at which version. That answer is deterministic: no model chooses it, so "what was this agent told on Tuesday" always has one answer.

An agent connected to the Contro1 MCP server then receives its skills four ways at once, because MCP clients differ in what they understand:

• MCP Skills extension (SEP-2640). The server declares io.modelcontextprotocol/skills and answers skills/list, skills/get and resources/read. A client that speaks the extension loads skills natively, with a sha256 digest for every file.
• Connection instructions. When the agent connects, it receives a short index of its skills and is told to load the matching one before starting a task. This works in every client today, including the ones that do not speak the extension yet.
• Tools. list_org_skills and get_org_skill, for clients that only call tools.
• Prompts. One per skill, so in Claude Code a person can run /mcp__contro1__refund-policy explicitly.

// skills/list (MCP Skills extension, SEP-2640)
{
  "resultType": "complete",
  "skills": [{
    "uri": "skill://contro1/refund-policy/SKILL.md",
    "frontmatter": {
      "name": "refund-policy",
      "description": "How we handle refund requests. Use for any refund or chargeback question.",
      "metadata": { "version": "4", "contro1-skill-key": "refund-policy" }
    },
    "resources": [
      { "uri": "skill://contro1/refund-policy/SKILL.md", "digest": "sha256:9f2c...", "size": 512 },
      { "uri": "skill://contro1/refund-policy/references/templates.md", "digest": "sha256:41ab...", "size": 1840 }
    ]
  }]
}

Pushing a skill to agents

In Skills > Library, choose Push to agents on a skill. You can push it to four kinds of target, each following the current version or pinned to a specific one:

Versions, publishing and rollback

Saving creates a draft. Drafts reach nobody. Publishing is a separate step, and before it you see who will change (named, with department and owner), who is protected by a pin or a freeze, which agents actually loaded the skill in the last 30 days, what changed in the text, and what the security scan said.

A published version never changes. To roll back, open the version history and choose Restore this version: Contro1 creates a new version with exactly that content and opens the same publish preview, so a rollback is reviewed like any other change.

For an agent doing real work, freeze it in Skills > Agents. A frozen agent keeps exactly the versions it has until someone chooses Upgrade to current. Nothing restarts: the agent sees the change on its next sync.

When a skill changes under an agent that is already connected

Contro1 does not push into a running session. Instead, the next time the agent calls any Contro1 tool, the result carries a short note about what changed since it connected: a skill newly pushed to it (named once, with what it is for), a new version of a skill it was shown, or a new version of a skill it actually loaded (repeated until it reloads).

What the agent already read earlier in the conversation stays in its context; the reload replaces it. If the agent asks for the version number it saw when it connected, it receives the current version with a note saying this one replaces the old copy, never an error. Pinned and frozen agents are not affected by a publish at all.

Security scanning

Skills are instructions that run with your agents' access, and research on public skills found that about one in four contains a vulnerability. Contro1 scans every saved version, every import and every skill found on employees' machines, once per distinct skill.

Importing a skill from a link

If the source changes between the preview and the import, the import is refused and you preview again: what becomes a draft is always what you read.

1. 1

   Paste a link

   A GitHub folder, a repository of skills, or a direct SKILL.md link.

2. 2

   Fetched and pinned

   Contro1 fetches over HTTPS and pins the exact commit.

3. 3

   Scanned

   All three engines run before anything is saved.

4. 4

   You read it

   The content and the findings, side by side.

5. 5

   Draft

   Imported as a draft. Publish it like any other skill.

Skills installed on employees' machines

People install skills themselves, into ~/.claude/skills, ~/.codex/skills, .cursor/skills and similar folders. Those change how their agents behave and nobody in the organization reviewed them. contro1 skills report finds them and reports them under the person's name, so they appear in Skills > Discovered on machines with their scan result and whether each is one of yours.

The command only reads. --dry-run shows exactly what would be sent, and --metadata-only sends names and fingerprints without content. From the Discovered view an administrator can read any reported skill and adopt it into the library as a draft.

contro1 auth login
contro1 skills report --dry-run    # see exactly what would be sent
contro1 skills report              # send it

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "contro1 skills report --every 24h --quiet" }] }
    ]
  }
}

For developers: the endpoints

Reading skills needs the skills:read scope (actions:read is also accepted for credentials issued earlier), or mcp:skills:read on a consented MCP connection.

Frequently asked questions

Does a skill give an agent permission to do what it describes?

No. A skill is guidance. Every Action is authorized by Contro1 when the agent calls it, from its grants and policies, whatever any skill says.

My MCP client does not support the new Skills extension. Will skills still work?

Yes. The connection instructions, the get_org_skill tool and the prompts work in every MCP client. Clients that do support SEP-2640 load the same skills natively.

What happens to a connected agent when I publish a new version?

Its next load returns the new version, and its next Contro1 tool call tells it which skill changed so it reloads. Pinned and frozen agents do not change.

How do I undo a bad publish?

Open the version history and choose Restore this version on the last good one. It is published as a new version through the same preview, so you see who it moves.

Does Contro1 block a skill the scanner flags as dangerous?

No. It shows the findings and asks the person publishing or pushing it to confirm by name. That confirmation, with their name and email, is recorded in the audit log.

Does contro1 skills report change or delete anything on my machine?

No. It reads skill folders and sends what it found. Use --dry-run to see exactly what would be sent first.

Related resources