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 Developer Tools → PolygentCode → Skills. Select a skill card to edit it, or use its switch and actions menu independently.

Permission	Capability
View Skills	View skill definitions and resources.
Manage Skills	Create, edit, enable, disable, and delete skills.

Start-ticket templates, automations, subagents, and AI job settings can restrict skills. Polygent Code bots expose all enabled skills; bots running on a command-line model always use Unrestricted. In a Skills picker:

• Unrestricted (all enabled skills) exposes every enabled skill.
• Restricted to selected skills with no selection exposes no skills.
• Restricted to selected skills with selections exposes only selected, enabled skills.
• When a tool allowlist is set, the Skill tool itself must also be allowed.
• 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 Developer Tools → PolygentCode → 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. Must equal the skill's saved name.
description	Required and concise; up to 1,024 characters; state what the skill does and when it applies.
Instructions	Actionable Markdown with at least one heading. Content that looks like a credential is rejected on save.

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 /. Skills configured for explicit invocation only still appear there, but Polygent Code does not choose them autonomously. The menu also lists command and skill files found in the repository's .claude/commands and .claude/skills folders and in the host account's ~/.claude folder; those are not filtered by the managed selection.

Autocomplete updates automatically after a skill is enabled, disabled, edited, or selected. Instruction changes apply to the next agent turn; a turn already running keeps the version it loaded. If deterministic behavior matters, avoid changing a skill while active sessions depend on it.

Repository skills

Skills committed to a repository are loaded from .polygent/skills, .agents/skills, and .claude/skills in the working copy, but only while the session's skills are Unrestricted.

A repository skill that is a link to a folder outside the working copy is refused unless that folder is listed in Harness:RepositorySkillExternalRoots in the API and Session Worker configuration. Review repository skills like any other code change — they are instructions the agent will follow.

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, that name matches the saved name, a heading exists, no credential-like text is present, and resource paths are valid.
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, the Skill tool is allowed, and the capability ceiling permits it. Start a new session.
Repository skill is ignored	Skills must be Unrestricted; a linked folder outside the working copy must be listed in Harness:RepositorySkillExternalRoots.
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	Send a new message after the current turn ends, or start a new session; verify the selected skill is the edited one.