Skill Creation

Overview

Create a new workspace skill directory and SKILL.md file following the Agent Skills Specification. A skill is a directory under .stencila/skills/ containing a SKILL.md file with YAML frontmatter and a Markdown body. Skills are reusable instruction sets for AI agents.

Skills should be self-contained. Do not rely on documentation or other content outside the skill directory. If the skill needs supporting material from elsewhere in the repository or from another source, copy it, summarize it, or excerpt it into files inside the skill's own references/ directory, then link to those local files from SKILL.md.

Steps

1. Determine the skill name from the user's request
2. Validate the name against the naming rules below
3. Resolve the closest workspace skill directory: walk up from the current directory to find the nearest directory containing .stencila/, or use the repository root if none exists
4. Create the directory <closest-workspace>/.stencila/skills/<name>/
5. Write the SKILL.md file with frontmatter and instructions, include activation keywords in the description so agents can match the skill to user requests
6. Add keywords to the frontmatter to improve discoverability and delegation accuracy, include terms reflecting likely user intents, artifacts, and domains
7. Replace placeholders such as TODO before considering the skill complete
8. If the skill depends on supporting guidance, examples, or specifications, create focused files in references/ and put that material there rather than referring to files elsewhere in the repo
9. Optionally create scripts/, references/, or assets/ subdirectories if the skill needs them
10. Validate the finished skill with stencila skills validate <name>, the skill directory path, or the SKILL.md path