skill-creator · diff
v1.0 to v1.0
34 added, 6 removed. Audit A to A.
---
name: skill-creator
- description: "Creates new AI agent skills following the Agent Skills spec. Trigger: When user asks to create a new skill, add agent instructions, or document patterns for AI."
+ description: "Create AI agent skills with valid frontmatter. Trigger: new skills, agent instructions, or documenting AI usage patterns."
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
## When to Create a Skill
Create a skill when:
- A pattern is used repeatedly and AI needs guidance
- Project-specific conventions differ from generic best practices
- Complex workflows need step-by-step instructions
- Decision trees help AI choose the right approach
**Don't create a skill when:**
- Documentation already exists (create a reference instead)
- Pattern is trivial or self-explanatory
- It's a one-off task
---
## Skill Structure
```
skills/{skill-name}/
├── SKILL.md # Required - main skill file
├── assets/ # Optional - templates, schemas, examples
│ ├── template.py
│ └── schema.json
└── references/ # Optional - links to local docs
└── docs.md # Points to docs/developer-guide/*.mdx
```
---
## SKILL.md Template
```markdown
---
name: {skill-name}
- description: >
- {One-line description of what this skill does}.
- Trigger: {When the AI should load this skill}.
+ description: "{What this skill does}. Trigger: {essential trigger words users or agents will say}."
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
## When to Use
{Bullet points of when to use this skill}
## Critical Patterns
{The most important rules - what AI MUST know}
## Code Examples
{Minimal, focused examples}
## Commands
```bash
{Common commands}
```
## Resources
- **Templates**: See [assets/](assets/) for {description}
- **Documentation**: See [references/](references/) for local docs
```
---
## Naming Conventions
| Type | Pattern | Examples |
|------|---------|----------|
| Generic skill | `{technology}` | `pytest`, `playwright`, `typescript` |
| Project-specific | `{project}-{component}` | `myapp-api`, `myapp-ui` |
| Testing skill | `{project}-test-{component}` | `myapp-test-sdk`, `myapp-test-api` |
| Workflow skill | `{action}-{target}` | `skill-creator`, `jira-task` |
---
## Decision: assets/ vs references/
```
Need code templates? → assets/
Need JSON schemas? → assets/
Need example configs? → assets/
Link to existing docs? → references/
Link to external guides? → references/ (with local path)
```
**Key Rule**: `references/` should point to LOCAL files, not web URLs.
---
## Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill identifier (lowercase, hyphens) |
- | `description` | Yes | What + Trigger in one block |
+ | `description` | Yes | Single-line, quoted YAML-safe string with what + `Trigger:` |
| `license` | Yes | Always `Apache-2.0` |
| `metadata.author` | Yes | `gentleman-programming` |
| `metadata.version` | Yes | Semantic version as string |
+ ### Description Rules
+
+ The `description` field is the skill-loading budget. Treat it as mandatory metadata, not prose.
+
+ - MUST be one physical line in frontmatter; never use `>` or `|` block scalars.
+ - MUST be YAML-safe: wrap the whole value in quotes and avoid unescaped matching quotes inside it.
+ - MUST include `Trigger:` and preserve the essential trigger words users or agents will actually say.
+ - SHOULD be <=160 chars; this is preferred for Claude Code skill-list budget.
+ - MUST be <=250 chars if a rare skill genuinely needs extra trigger coverage.
+ - MUST NOT add `Keywords`; put concise trigger keywords in `description` instead.
+
+ Good:
+
+ ```yaml
+ description: "Create Jira tasks in the team format. Trigger: Jira task, ticket, issue, or task creation."
+ ```
+
+ Bad:
+
+ ```yaml
+ description: >
+ Create Jira tasks in the team format.
+ Trigger: Jira task, ticket, issue, or task creation.
+ Keywords: jira, task
+ ```
+
---
## Content Guidelines
### DO
- Start with the most critical patterns
- Use tables for decision trees
- Keep code examples minimal and focused
- Include Commands section with copy-paste commands
+ - Keep frontmatter descriptions concise with essential trigger keywords
### DON'T
- Add Keywords section (agent searches frontmatter, not body)
+ - Use multiline, unquoted, or block-scalar frontmatter descriptions
- Duplicate content from existing docs (reference instead)
- Include lengthy explanations (link to docs)
- Add troubleshooting sections (keep focused)
- Use web URLs in references (use local paths)
---
## Registering the Skill
After creating the skill, add it to `AGENTS.md`:
```markdown
| `{skill-name}` | {Description} | [SKILL.md](skills/{skill-name}/SKILL.md) |
```
---
## Checklist Before Creating
- [ ] Skill doesn't already exist (check `skills/`)
- [ ] Pattern is reusable (not one-off)
- [ ] Name follows conventions
- - [ ] Frontmatter is complete (description includes trigger keywords)
+ - [ ] Frontmatter is complete (description is quoted, one-line, YAML-safe, includes `Trigger:`)
+ - [ ] Description is ideally <=160 chars and never >250 chars
+ - [ ] Description preserves essential trigger words; no `Keywords` section added
- [ ] Critical patterns are clear
- [ ] Code examples are minimal
- [ ] Commands section exists
- [ ] Added to AGENTS.md
## Resources
- **Templates**: See [assets/](assets/) for SKILL.md template