AGENT SKILL

create-skill

Create or update Astravia-compatible Agent Skills. Use when the user asks to create a skill, add a SKILL.md workflow, register a skill in skills-manifest.json, package a skill in a Astravia plugin, or add a built-in Astravia skill preset.

License 许可
Apache-2.0
最近更新
2026-11-15
Stars
★ 53
Forks
25

01 前言 Front Matter

name
create-skill
description
Create or update Astravia-compatible Agent Skills. Use when the user asks to create a skill, add a SKILL.md workflow, register a skill in skills-manifest.json, package a skill in a Astravia plugin, or add a built-in Astravia skill preset.

02 资源文件 1

03 SKILL.md 正文

Create a Astravia Skill

Create focused Agent Skills that Astravia can execute and display. Treat the Skill files and their registration metadata as one change.

Choose the target

Infer the target from the request. If it is ambiguous, ask the user to choose before writing files.

Target Skill directory Required registration
Global Astravia product skill ~/.astravia/skills/<skill-name>/ Update ~/.astravia/skills-manifest.json.
Project skill <project-root>/.astravia/skills/<skill-name>/ No global manifest entry; project discovery is directory-based.
Plugin skill <plugin-root>/agent/skills/<skill-name>/ Update plugin.json under agent.skillPaths.
Built-in Desktop skill <astravia-mono>/packages/skill-presets/<skill-name>/ Update <astravia-mono>/packages/skill-presets/skills-manifest.json.

Do not place a global product Skill only in ~/.astravia/agent/skills; that directory is Agent-compatible but does not provide the Astravia product registration metadata required by the Skills UI.

Understand the directory protection

Skill roots — ~/.astravia/skills, ~/.astravia/agent/skills, <project-root>/.astravia/skills, and the .agents/skills equivalents — are read-only so that generated artifacts never land in them. Creating a new <root>/<skill-name>/ directory is exempt: once this session authors that directory, every file inside it stays writable for the rest of the session.

An already-installed Skill stays read-only. write and edit reject its files, and a shell command that touches them returns a warning to move the output out. To change one, edit the source it was installed from — the plugin, the repository preset, or the project directory — or ask the user to uninstall it first. Never work around the rejection with shell redirection.

Create the Skill

  1. Convert the requested name to lowercase kebab-case. It must be 1-64 characters containing only lowercase letters, digits, and hyphens. The directory name must match the frontmatter name.
  2. Inspect nearby Skills and relevant project documentation before writing. Reuse established terminology and tool names without copying unrelated instructions.
  3. Create <skill-directory>/SKILL.md with YAML frontmatter containing name and description.
  4. Write the body as imperative workflow instructions. State when to inspect context, when to ask a question, what files to create or edit, and how to verify completion.
  5. Add scripts/, references/, or assets/ only when genuinely required. Keep detailed reference material outside SKILL.md and link to it with relative paths.
  6. Do not overwrite an existing Skill or unrelated configuration without reading it first. Ask before replacing intentional behavior. Inside a protected root, an existing Skill directory cannot be overwritten at all — see the directory protection above.

Use this minimal structure:

---
name: example-skill
description: Describe what the Skill does and the user requests that should trigger it.
---

# Example Skill

Concise workflow instructions.

Register a global Astravia Skill

Read the full ~/.astravia/skills-manifest.json before editing it. The file is a root-level JSON object keyed by Skill name. Preserve every existing entry and add or update only the target Skill.

Use an entry shaped like this:

{
  "example-skill": {
    "name": "example-skill",
    "version": "1.0.0",
    "installedAt": "<current ISO-8601 timestamp>",
    "source": "custom",
    "enabled": true,
    "type": "skill",
    "alias": "Optional display name",
    "description": "Description aligned with SKILL.md frontmatter"
  }
}

If the manifest does not exist, create it as {} before adding the entry. Keep it valid JSON and avoid replacing unrelated Skills. Use the actual current timestamp rather than a placeholder.

Register a built-in Desktop Skill

Read the full packages/skill-presets/skills-manifest.json. Preserve existing entries and add the new Skill with source: "builtin", enabled: true, type: "skill", a version, and display metadata. The manifest key, entry name, directory name, and SKILL.md frontmatter name must all match.

The Desktop build only packages enabled directories registered in this manifest. An unregistered preset is an error.

Update plugin configuration

Only plugin-packaged Skills use plugin.json registration.

  1. Read the full plugin.json before editing it.
  2. Preserve every existing agent field and every existing skillPaths entry.
  3. Add a plugin-relative path. Prefer a shared parent such as "agent/skills" when it intentionally contains all plugin Skills; otherwise add the specific Skill directory.
  4. Do not add duplicate paths.

Example:

{
  "agent": {
    "skillPaths": ["agent/skills"]
  }
}

Quality rules

  • Keep the frontmatter valid YAML at the start of the file.
  • Make description specific enough for reliable triggering; include both the capability and common request language.
  • Keep SKILL.md under 500 lines. Move large examples and domain references into references/.
  • Use relative links for files inside the Skill directory.
  • Do not hardcode secrets, machine-specific absolute paths, or destructive commands.
  • Prefer the minimum files and instructions needed for the requested workflow.

Verify

  1. Confirm the final directory matches the selected target.
  2. Confirm SKILL.md exists and its frontmatter name matches the directory.
  3. Confirm the description clearly states when the Skill should run.
  4. For global or built-in Skills, parse the complete skills-manifest.json and confirm the target entry is present without losing existing entries.
  5. For plugin Skills, confirm plugin.json contains the correct relative agent.skillPaths entry and remains valid JSON.
  6. Report created or modified files and any validation that was not run.

04 同仓库更多 Skills

maomaochong-ai
maomaochong-ai/open-astravia

publish-ability

Publish a skill, MCP server, plugin, or bundle to the Astravia ability marketplace. Use when the user asks to upload/publish/submit an ability, put a plugin on the marketplace, share a skill with other users, or migrate an existing package into Astravia.

★ 53
maomaochong-ai
maomaochong-ai/open-astravia

install-ability

在本机 Astravia 中安装能力——插件(plugin)、Skill 与 MCP 服务器。用户说「装一个插件 / install plugin / 从能力市场安装 / 加一个 MCP server / 配置 MCP / 装个 skill」,或插件装完没生效、需要 reload、pending 版本没应用时使用。不用于安装 npm 依赖、IDE 插件、浏览器扩展,也不用于开发插件(那是 plugin-workbench)或创作 Skill(那是 create-skill)。

★ 53
maomaochong-ai
maomaochong-ai/open-astravia

remotion-video

Create, modify, and render Remotion React video projects in the current Astravia conversation workspace. Use for requests to make programmatic videos, motion graphics, animated explainers, social videos, data videos, or to edit an existing Remotion composition and export it as MP4.

★ 53
maomaochong-ai
maomaochong-ai/open-astravia

plugin-workbench

Create, implement, build, pack, install, reload, and manage Astravia desktop plugins for non-developers. Use whenever the user wants a Astravia plugin, plugin scaffolding, apply a `.astraviapkg` package to Astravia, edit plugin.json name/guidingWords, or debug plugin load/install. Requires the Plugin Workbench input-bar toggle (hard isolation). The plugin handbook ships inside the project's own @astravia-org/plugin-sdk; locate it with the bundled CLI's docs command.

★ 53
maomaochong-ai
maomaochong-ai/open-astravia

review-content-quality

Evaluate generated images and videos against their creative brief, delivery requirements, continuity rules, and technical quality, then propose the smallest evidence-based repair. Use when the user asks whether an output is good, requests critique or selection among variants, reports weak or broken media, or before expanding an approved direction into more assets.

★ 53
maomaochong-ai
maomaochong-ai/open-astravia

operate-content-workflow

Inspect, diagnose, create, edit, connect, and run Astravia content-creation node workflows. Use when the user asks to build or modify a content workflow, refers to selected canvas nodes, wants to understand workflow or generation status, needs an image/video generation failure diagnosed, or asks the agent to operate the content-creation canvas.

★ 53