Create a Workspace Skill

Goal

Create a discoverable, testable Workspace Skill in the current project so future tasks can reuse team conventions instead of explaining them from scratch every time.

Before you begin

• Use a project that has already been added. Workspace Skills are stored under .agents/skills/ in that project.
• Identify a stable, repeated workflow, such as “write change notes in the team's format.” Do not turn a one-off request into a Skill.
• Prepare two or three real examples and clear success criteria.
• Confirm that the built-in skill-creator Skill is enabled and appears in the input box's Skill picker.

Steps

1. Select Skill Creator in a conversation

In the project conversation input box, select Add context (+), then Skills, and search for skill-creator. Selecting it only adds the Skill to the current task. The Skill itself does not automatically receive file, command, or network permissions.

2. Describe the behavior you want to capture

Send a specific task:

Use skill-creator to create a Workspace Skill for this project.

Name: release-note-helper
Purpose: Write Chinese change notes from the actual Git diff.
Trigger: The user asks for release notes or a change summary for a monthly report.
Requirements:
- Read the actual diff first; do not infer changes from conversation memory.
- Organize the result into “Added, Fixed, Risks, and Verification.”
- Never say a test passed without evidence.
- Do not run git commit, push, or any release operation.

First propose the Skill structure and two examples, then create the files. When finished, run static checks and explain how to validate it in a new task.

Skill Creator creates an exact-case SKILL.md as needed and may add references/, templates/, assets/, or scripts/. Keep the content focused on the working method; do not place large amounts of generic knowledge in the entry file.

3. Review the files

Before approving a write, verify that the target is under:

.agents/skills/release-note-helper/

Check that the name, description, and trigger conditions in SKILL.md are clear and that every resource file is necessary. Workspace Skills come from project content and should be treated as untrusted input by default.

4. Validate it in a new conversation

Create a new project conversation, refresh the Skill picker, select the new Skill, and test it with a real example. The current Run does not hot-load a Workspace Skill that was just created or modified, so do not claim that behavior was validated in the same Run that created it.

Check three things during validation: whether the Skill is easy to discover correctly, whether it performs as required, and whether it triggers incorrectly on unrelated tasks. If changes are needed, revise the files and validate again in another new Run.

Expected result

The project contains a structurally valid .agents/skills/<name>/SKILL.md. A new conversation can discover and select it, and actual test output meets the success criteria. A Workspace Skill is visible only to the current project and is not automatically installed in the global Skill list.

Troubleshooting

• Skill Creator is missing: Go to Settings → Skills, confirm that it is enabled, then refresh the input box's Skill catalog.
• The new Skill does not appear: Start a new conversation or Run and refresh the catalog. Confirm that the filename is exactly SKILL.md.
• Name conflict: Give the Skill a more specific, unique name instead of relying on ambiguous same-name overrides.
• The script does not run: Skill Scripts currently support only Python scripts declared by the Skill, require Full access, and require approval for every execution. Missing dependencies are not installed automatically.
• You want to modify an installed Skill: Do not edit the application-managed directory directly. Copy it into the Workspace as an editable version, then review and test it.

Continue with Skill and MCP and Write effective tasks.