Skip to content

aalmada/agent-package-manager-extension / .agents/skills/create-skill

create-skill

Verified

Create or update AI agent skills (SKILL.md + reference files) for any harness that supports the format: GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Kiro, OpenCode, and more. Use when: authoring a new skill from scratch, improving or restructuring an existing skill, deciding how to split content across files, writing skill frontmatter, choosing trigger phrases for the description field, organizing reference files. Covers skill architecture, compact writing rules, frontmatter constraints, and research using official documentation and Microsoft Learn. DO NOT USE FOR: general coding tasks, VS Code extension development, non-skill documentation.

FileKindSize
SKILL.mdskill md3.5 KB
references/research-workflow.mdmarkdown2.0 KB
references/structure.mdmarkdown5.1 KB

references/structure.md

View on GitHub
# Skill Structure Reference

Skills are a cross-harness convention, not a single-tool feature — Copilot, Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Kiro, OpenCode, and others all discover skills the same way.

## Folder Layout

```text
.agents/skills/<skill-name>/     # harness-neutral (preferred); every harness above reads this path
  SKILL.md
  references/

~/.agents/skills/<skill-name>/   # user-global (all workspaces)
```

Some harnesses also accept their own native path alongside `.agents/skills/`: `.github/skills/<name>/` (Copilot), `.claude/skills/<name>/` (Claude Code). When authoring through APM, source lives at `.apm/skills/<name>/SKILL.md`; `apm install`/`apm compile` deploys the harness-neutral copy automatically.

## SKILL.md Frontmatter Spec

| Field | Required | Constraint | Notes |
| --- | --- | --- | --- |
| `name` | yes | kebab-case | Must match folder name |
| `description` | yes | ≤1024 chars | Semantic trigger for agent |

## Description Template

```text
<Primary action verb> <domain>. Use when: <trigger list>. [Covers: <key topics>.] [DO NOT USE FOR: <exclusions>.]
```

- Lead with verb: "Create", "Configure", "Debug", "Migrate"
- Name concrete tasks and include terms users actually type; do not reword the skill name as a description
- Trigger list: semicolons, no articles, keyword-dense
- Exclusions prevent false activations — include them
- Name the better skill when excluding a nearby scope
- Count chars: `echo -n "text" | wc -c`

## YAML Safety in Descriptions

**Always wrap the `description` value in double quotes** (`description: "..."`). Trigger-phrase descriptions routinely contain colons ("USE FOR:", "DO NOT USE FOR:", "Use when:"), and an unquoted YAML plain scalar treats a colon followed by a space mid-value as the start of a new mapping key — this throws a real parse error (`bad indentation of a mapping entry` / `mapping values are not allowed in this context`) in any strict YAML parser, including tools that load SKILL.md frontmatter directly. Earlier guidance in this repo assumed that was "tolerated" because apm's own frontmatter reader was regex-based — that assumption was wrong: other tooling (e.g. editor extensions) does strict-parse this frontmatter and fails loudly. Quoting is the only reliable fix; don't rely on rewording to dodge colons.

Inside a double-quoted scalar, only two characters need escaping: `\"` and `\\`. Everything else — colons, single quotes/apostrophes, backticks, parentheses — is safe as-is.

| Sequence | Effect | Fix |
| --- | --- | --- |
| Colon + space mid-value | Starts a new mapping key in an unquoted scalar — parse error | Wrap the whole value in double quotes |
| Space + `#` | Starts a YAML comment — silently drops everything after it, with no error, even when quoted incorrectly | Keep the value inside the quotes; never let a `#` fall outside them |
| Literal `"` inside the value | Would end the quoted scalar early | Escape as `\"` |
| Leading `- ? : , [ ] { } # & * ! \| > ' " % @` \` (if ever unquoted) | A scalar can't start with these unquoted | Moot once the whole value is quoted |

Verify: `node -e "const yaml=require('js-yaml'); const fm=require('fs').readFileSync('SKILL.md','utf8').match(/^---\n([\s\S]*?)\n---/)[1]; console.log(yaml.load(fm))"` — this must succeed without throwing and print the full, untruncated description.

## Reference File Conventions

| Convention | Rule |
| --- | --- |
| Naming | lowercase, hyphen-separated |
| Scope | one topic per file |
| Size | ≤200 lines; split if larger |
| Linking | use relative markdown links in SKILL.md table |
| Load hint | every ref file must have a row in SKILL.md table |

## Scripts & Assets

| Directory | Use For | Notes |
| --- | --- | --- |
| `scripts/` | Automation run by skill (e.g. codegen, scaffolding) | Python preferred; any language permitted |
| `assets/` | Templates, sample data, images | Link from SKILL.md or reference files |

A `scripts/` script isn't limited to pure deterministic code — it can embed the [copilot-sdk](../../../../apm_modules/netfabric/intelligentium/plugins/agent-authoring/.apm/skills/copilot-sdk/SKILL.md) to call out to Copilot for one bounded, non-deterministic step (e.g. classify input, summarize a diff) and then resume deterministic control flow. Use this when only part of the pipeline needs judgment; keep the AI call scoped to that step so the rest of the script stays testable and reproducible.

## SKILL.md Required Sections

1. Frontmatter
2. Anatomy table (files + purpose + size)
3. Core quick-reference (tables/code, ≤3 sections)
4. Reference file table (file | load when)

## Content Placement

Keep in `SKILL.md`:

- Scope, trigger phrases, and exclusions
- Anatomy and quick-reference facts
- The shortest complete workflow
- Reference links with precise load conditions

Move to references:

- Full API or field tables
- Extended examples
- Edge cases and compatibility notes
- Background needed only for uncommon decisions

## Anti-patterns

- ❌ Single flat SKILL.md with all detail
- ❌ Description > 1024 chars
- ❌ Reference files not listed in SKILL.md table
- ❌ `name` field mismatching folder name
- ❌ Duplicate content across SKILL.md and references
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall