docs(skill-authoring): allow argument-hint as optional frontmatter#132
Conversation
The "Optional fields" line read as a closed allow-list, so a policy reviewer blocked adding the real Claude Code `argument-hint:` slash-command field. Add it (with an example) and state explicitly the list is illustrative — agents preserve unrecognized frontmatter and ignore fields they don't use, mirroring rule-frontmatter passthrough. Closes #117 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the skill-authoring policy documentation to explicitly treat argument-hint as a supported/recognized optional SKILL.md frontmatter field and to remove the “closed allow-list” interpretation that was blocking downstream usage (Issue #117 / referenced kit PR #89).
Changes:
- Expands the
SKILL.mdoptional-frontmatter guidance to includeargument-hintwith an example value. - Rephrases the optional-field line (“include…”) and adds an explicit note that the list is illustrative (unknown fields are preserved/ignored as applicable).
- Adds a CHANGELOG entry describing the policy clarification and its motivation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| rules/skill-authoring.md | Clarifies optional skill frontmatter fields (adds argument-hint, removes closed-list reading). |
| CHANGELOG.md | Records the policy clarification/motivation as a new top-of-file (unheaded) Rules entry. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see rules/author-model-declaration.md.
Generated by PR Policy Review (Anthropic) for issue #132 · ● 310.4K
There was a problem hiding this comment.
Policy loaded: 20 rule files from rules/ (PR head).
The changed rule prose violates rules/context-writing-style.md: the new SKILL.md Frontmatter optional-fields sentence uses multiple parenthetical clauses where the policy requires at most one per sentence. Split the field list and field explanations into separate bullets or sentences before merging.
Generated by PR Policy Review (OpenAI) for issue #132
The OpenAI policy reviewer flagged the combined optional-fields bullet for stacking two parenthetical clauses, which context-writing-style limits to one per sentence. Move argument-hint's explanation to a dedicated bullet so each bullet carries at most one parenthetical. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see rules/author-model-declaration.md.
Generated by PR Policy Review (Anthropic) for issue #132 · ● 211.1K
There was a problem hiding this comment.
Policy loaded: 20 rule files from rules/ (PR head).
All rules pass — no violations found.
Generated by PR Policy Review (OpenAI) for issue #132
A stray publish run double-published 0.3.59 content as 0.3.60 and never committed the bump back to main, leaving a registry version with no CHANGELOG entry. Record it for history honesty so the next release (0.3.61) does not silently skip 0.3.60. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see rules/author-model-declaration.md.
Generated by PR Policy Review (Anthropic) for issue #132 · ● 315.3K
There was a problem hiding this comment.
Policy loaded: 20 rule files from rules/ (PR head).
All rules pass — no violations found.
Generated by PR Policy Review (OpenAI) for issue #132
Author-Model: claude-opus-4-8
Summary
argument-hintto the optionalSKILL.mdfrontmatter list inrules/skill-authoring.md, on its own explanation bullet with an example value.rules/rule-frontmatter.mdpassthrough).rules/context-writing-style.md(round-1 reviewer flagged the combined bullet).Why
argument-hintis real Claude Code slash-command frontmatter — the UI surfaces the expected argument shape inline next to the command. It has no runtime semantics, and other agents (Codex, Gemini, OpenCode) ignore unknown fields. The rule's closed-list phrasing caused the OpenAI policy reviewer onintent-integrity-chain/kitPR #89 to block its addition.Closes #117
Bundled CHANGELOG reconciliation (out of band)
This PR also adds a
## 0.3.60CHANGELOG entry recording that 0.3.60 was a duplicate re-publish of 0.3.59 (a stray publish run shipped identicalmaincontent and never committed its bump back tomain, so the registry advanced to 0.3.60 with no CHANGELOG entry). Recorded here so this PR's release (0.3.61) does not silently skip 0.3.60. No code/rule impact.Test plan