Skip to content

Clarify frontmatter requirements in contributing-skills.md #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wise-king-sullyman wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −1
Open

Clarify frontmatter requirements in contributing-skills.md #38

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion CONTRIBUTING-SKILLS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,11 @@ Your skill becomes available as `/<plugin-name>:your-skill-name` for anyone who
Here's an example `summarize` skill — the entire file:

```markdown
---
name: summarize
description: Summarize code, files, PRs, or directories for a mixed audience
---

Provide clear, concise summaries of code, files, pull requests,
or entire directories. Write for a mixed audience of designers,
developers, and stakeholders.
Expand Down Expand Up @@ -138,7 +143,16 @@ developers, and stakeholders.
- Shorter is better.
```

That's it. No frontmatter required. No code. No config. Just instructions in markdown.
Every SKILL.md needs YAML frontmatter with a `name` and `description` so the plugin system can discover it:
Copy link
Collaborator

@jpuzz0 jpuzz0 Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to push back on "needs" here.

Here's a working example with no frontmatter: unit-test-generator/SKILL.md — it registers fine as /pf-react:unit-test-generator:
Image

Skills are discovered by directory path, not frontmatter. A description is important — but it can just be the first line of the SKILL.md, it doesn't need to be in YAML frontmatter. And name is redundant since the directory name is the skill name.

Copy link
Author

@wise-king-sullyman wise-king-sullyman Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, when I first tried to use my skill without adding the frontmatter claude couldn't find it or this unit-test-generator skill 🤔

Copy link
Collaborator

@jpuzz0 jpuzz0 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How were you trying to find it exactly? Maybe you could demonstrate this. I don't mind making it a requirement - but it seems its not at least in terms of Claude Code discovery.

Copy link
Collaborator

@jpuzz0 jpuzz0 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking into this more - the skills npm package (a 3rd party tool) does not discover skills unless they have a "name" - so that's an incentive here at least. Also, the Claude code official docs do cite it - linked to slash command usage - https://code.claude.com/docs/en/skills. So I think this is enough to just make it a requirement for us.


```yaml
---
name: summarize
description: Summarize code, files, PRs, or directories for a mixed audience
---
```

After the frontmatter, it's just instructions in markdown. No code. No config.

## Skill ideas to get you started

Expand Down