Thanks for stopping by. This document explains what kinds of contributions are welcome, where to file them, and the ground rules that keep this repo maintainable.
Typo fixes, clearer phrasing, better examples, and additional guides for SPECIFICATION.md or README.md are all appreciated. Keep changes focused and preserve the existing tone.
Spotted an incorrect parse, a mismatch between the spec and the reference parser, or a broken example? Open an issue with a minimal reproduction (a small SKILL.md snippet plus expected vs. actual output goes a long way).
Want to suggest a new attribute, a section tag change, or discuss a design trade-off? Start a discussion rather than opening an issue. Issues are reserved for concrete defects; Discussions are for ideas and open-ended exchange.
Ground your proposal in an actual problem you hit while authoring or parsing skills. Every new rule in the spec is a rule every implementer has to honour, so the bar for additions is intentionally high. When in doubt, leave it out.
Not sure where to post? Default to Discussions. If it turns out to be a defect we can act on, we will convert it to an issue.
The parser under src/ is intentionally small and opinionated. It aims to stay a pure text-to-data function with no runtime dependencies. Refactors that keep the behaviour identical while improving readability, error messages, or type inference are welcome. Feature additions should be discussed first.
To keep scope manageable during early iteration, the following are out of bounds for now:
- Community skill submissions - this repo is the spec plus parser, not a skill directory.
- Frontmatter support - the whole point of this variant is to omit frontmatter entirely.
- Sweeping architectural rewrites - small, focused changes only.
If you are unsure whether something fits, open a Discussion before writing the code.
The parser and tests run under Deno.
# Format, lint, and type-check the source
deno task check
# Run the test suite
deno task testThe npm distribution is produced with unbuild:
npm install
npm run build- Fork the repository.
- Create a branch off
mainfor your work. - Make the change and verify it locally with
deno task checkanddeno task test. - Open a pull request against
main, describing what changed and why.
Keep each pull request focused on one logical change. Link any related issues or discussions.
Using an AI assistant (Claude, GPT, Copilot, agent frameworks, and so on) to help with a contribution is fine and often useful. Please disclose it in the pull request or issue description, along with a rough sense of how the tool was used (for example, "AI drafted the initial parser refactor; I reviewed and rewrote the error paths").
An example disclosure line is enough:
Parts of this PR were drafted with the help of Claude Code, then reviewed and edited manually.
Trivial fixes (typos, whitespace, dead links) do not need a disclosure.
Undisclosed AI-generated code makes review harder and wastes reviewer attention. Contributions that appear to skip disclosure may be closed without merge.
- Clear disclosure if AI assistance was involved.
- Your own understanding of every changed line - you should be able to answer questions about it.
- A short rationale explaining why the change is needed.
- Tests or examples demonstrating the new behaviour or the regression the change fixes.
By contributing, you agree that your contributions will be licensed under the Apache License 2.0 for code and specification files, and CC-BY 4.0 for documentation.