Skills

A skill is a reusable instruction pack that Polygent Code loads on demand when its description matches the current task. For the effective session boundary around skill tools, see Harness tool and MCP scoping.

Access and scope

Skills are centrally managed and exposed only when both globally enabled and allowed by the session source.

Open Dev Tools → Polygent Code → Skills. Select a skill card to edit it, or use its switch and actions menu independently.

Permission	Capability
skills.view	View skill definitions and resources.
skills.manage	Create, edit, enable, disable, and delete skills.

Bots, start-ticket templates, automations, and supported session configuration can restrict skills. In a Skills picker:

• Unrestricted exposes all enabled skills.
• Restricted with no selection exposes no skills.
• Restricted with selections exposes only selected, enabled skills.
• The Selected skills User Setting must also be enabled.
• Workspace capability limits can further reduce the effective set.

Create a skill

Skill authoring defines the discovery metadata and the instructions loaded by the agent.

1. Open Dev Tools → Polygent Code → Skills.
2. Select Create Skill.
3. Enter the name, description, and SKILL.md content.
4. Enable the skill when it is ready for use.
5. Save, then reopen it to add optional resources.
6. Select the skill in the intended bot, template, automation, or session source.
7. Start a new session and verify that the skill is available.

Required format

SKILL.md uses YAML frontmatter followed by Markdown instructions.

---
name: release-check
description: Validate a release candidate and report blocking deployment issues.
---

# Release check

Run the repository's supported validation and report every blocking failure.

The file must follow the Agent Skills specification.

Field	Requirement
name	Unique; 1–64 lowercase letters, digits, or hyphens; no leading, trailing, or consecutive hyphens.
description	Required and concise; up to 1,024 characters; state what the skill does and when it applies.
Instructions	Actionable Markdown that does not depend on hidden operator knowledge.

tip

A precise description is the main discovery control. Include the task type and trigger conditions; do not put the full procedure in the description.

Resource files

Resources package supporting content with the skill while keeping the main instructions concise.

After the first save, add files only under:

• scripts/ for scripts the instructions explicitly invoke;
• references/ for material loaded when needed;
• assets/ for templates or other output resources.

Reference resources with relative paths from SKILL.md. Do not store credentials, tokens, private keys, or environment-specific secrets in skill files. Treat scripts as executable content and review them before enabling the skill.

Updates and session behavior

Enabled skills allowed for the current session appear in the chat composer's Skills section when you type /, including while filesystem suggestions are temporarily unavailable during session preparation. Skills configured for explicit invocation only still appear there, but Polygent Code does not choose them autonomously. Disabled skills and skills outside the session's effective selection are omitted.

Autocomplete updates automatically after a skill is enabled, disabled, edited, or changed in a bot selection. Skill instruction changes affect newly prepared session runs; an already running turn may continue with the version it loaded.

After editing, enabling, disabling, or changing a selection, send a new message after the session has resumed or start a new session. If deterministic behavior matters, avoid changing a skill while active sessions depend on it.

Operational guidance

Skill governance keeps instructions predictable and limits accidental privilege expansion.

• Keep one focused responsibility per skill.
• Prefer repository commands described generically unless a specific operator command is required.
• State required tools and prerequisites in the instructions.
• Keep large background material in references/ and load it only when needed.
• Disable obsolete skills before deleting them, then verify no session source still selects them.
• Review skill scripts and external links as untrusted operational content.
• Pair skill selection with the narrowest tool and MCP allowlists required.

Troubleshooting

Skill troubleshooting starts with validation, global state, and effective session scope.

Symptom	Resolution
Save is rejected	Validate YAML frontmatter, required fields, naming rules, and resource paths.
Skill is absent from a picker	Confirm the skill is enabled and the viewer has permission. Refresh the page after saving.
Skill is in a picker but unavailable to the agent	Confirm it is selected or unrestricted, Selected skills is enabled, and workspace capability limits permit it. Start a new session.
Agent does not choose the skill	Rewrite the description with explicit task triggers, or instruct the agent to use the skill by name.
Resource cannot be opened	Confirm it is under an allowed resource directory and that the relative path and filename casing match.
Updated instructions are not observed	Resume with a new message or start a new session; verify the enabled skill being selected is the edited one.