Skip to content

docs(readme): project-first guidance and skills list format#78

Merged
odinr merged 3 commits intomainfrom
feat/readme-skills-list-format
Mar 12, 2026
Merged

docs(readme): project-first guidance and skills list format#78
odinr merged 3 commits intomainfrom
feat/readme-skills-list-format

Conversation

@odinr
Copy link
Collaborator

@odinr odinr commented Mar 11, 2026

Why

The README and generator flow had three problems:

  • install guidance mixed project/global workflows in a way that was less clear for team onboarding,
  • skills were presented in a dense table format,
  • frontmatter parsing could truncate descriptions containing # inside quoted strings (for example "solve #123").

Current behavior

  • install and update/check guidance in README was less explicitly project-first,
  • skills in README were table-based,
  • parser removed everything after inline #, even when # appeared inside quoted values.

New behavior

README install guidance is explicitly project-first, with global install/check/update moved into an optional section.

Skills are listed as a formatted list:

**👍 [`fusion-issue-author-bug@0.1.2`](skills/fusion-issue-author-bug/SKILL.md)**

Authors a GitHub issue in a bug report style.

---

**🧪 [`fusion-dependency-review@0.1.0`](skills/.experimental/...)**

...
  • Type icon is derived from skill path prefix: 🧪 .experimental/ · 👌 .curated/ · ⚙️ .system/ · 👍 default
  • Version is embedded directly in the link label as skill-name@version
  • Entries are separated by --- horizontal rules
  • Frontmatter parsing now preserves # inside quoted strings while still stripping unquoted inline comments
  • Generator/docs naming updated from table-oriented wording to list-oriented wording
  • Generator (update-readme-skills-table.ts), parser (parse-frontmatter.ts), tests, and README all updated

References

  • Issue(s): N/A
  • Related PR(s): N/A
  • Docs / specs: N/A

Reviewer focus

  • Start here:
    • scripts/release-prepare/update-readme-skills-table.ts (buildSkillsList, list rendering)
    • scripts/list-skills/parse-frontmatter.ts (stripInlineComment)
  • Verify these behavior changes:
    • README install guidance is project-first,
    • README skills section renders as a list,
    • fusion-issue-solving description is no longer truncated.
  • Risky or security-sensitive parts: None

Self review checklist

  • I scoped this PR to one clear purpose.
  • I followed CONTRIBUTING.md.
  • I did not include secrets, credentials, or sensitive data.
  • I reviewed my own diff for clarity and unintended changes.

- Drop markdown table in favour of bold link + description entries
- Format: **icon `skill-name@version`(link)** / description / ---
- Add type icon prefix derived from skill path (.experimental/curated/system/default)
- Update generator, tests, and regenerate README
@odinr odinr self-assigned this Mar 11, 2026
@odinr odinr requested a review from Copilot March 11, 2026 17:10

This comment was marked as resolved.

@odinr odinr requested a review from a team as a code owner March 12, 2026 06:25
@odinr odinr changed the title feat(readme): replace skills table with formatted skill list docs(readme): project-first guidance and skills list format Mar 12, 2026
@odinr odinr force-pushed the feat/readme-skills-list-format branch from 1b703ae to f0ca861 Compare March 12, 2026 06:31
@odinr odinr merged commit 31f7b26 into main Mar 12, 2026
5 checks passed
@odinr odinr deleted the feat/readme-skills-list-format branch March 12, 2026 06:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants