Add single source of truth for skills with cross-tool sync#17
Open
gius wants to merge 1 commit into
Open
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces a “single source of truth” for COG skills and propagates those skill definitions into tool-native formats (Claude Code, Gemini CLI, Kiro), alongside version/doc updates.
Changes:
- Adds
.agents/skills/**/SKILL.mdas canonical skill definitions (agentskills.io-style frontmatter) and updates generated skill files for Claude/Gemini/Kiro. - Adds/updates Gemini CLI command entrypoints (
.gemini/commands/*.toml) for broader skill parity. - Updates plugin metadata (version bump + directory structure path change) to match the new layout.
Reviewed changes
Copilot reviewed 81 out of 111 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| .kiro/powers/cog-generate-release-notes/POWER.md | Adds a new Kiro power definition for release notes generation. |
| .kiro/powers/cog-generate-prd/POWER.md | Adds a new Kiro power definition for PRD generation. |
| .kiro/powers/cog-export-open-issues/POWER.md | Adds a new Kiro power definition for open-issues export. |
| .kiro/powers/cog-create-user-story/POWER.md | Adds a new Kiro power definition for creating user stories. |
| .kiro/powers/cog-auto-research/POWER.md | Adds a new Kiro power definition for auto-research. |
| .gemini/skills/update-knowledge-base.md | Adds Gemini playbook for updating the knowledge base. |
| .gemini/skills/update-cog.md | Expands Gemini playbook for updating COG from upstream. |
| .gemini/skills/scout.md | Adds Gemini playbook for URL/tool triage (“scout”). |
| .gemini/skills/publish-to-confluence.md | Adds Gemini playbook for Confluence publishing with approval gate. |
| .gemini/skills/meeting-transcript.md | Adds Gemini playbook for processing meeting transcripts. |
| .gemini/skills/generate-release-notes.md | Adds Gemini playbook for release notes generation. |
| .gemini/skills/generate-prd.md | Adds Gemini playbook for PRD generation. |
| .gemini/skills/export-open-issues.md | Adds Gemini playbook for open-issues export. |
| .gemini/skills/create-user-story.md | Adds Gemini playbook for creating user stories. |
| .gemini/skills/auto-research.md | Adds Gemini playbook for auto-research. |
| .gemini/commands/weekly-checkin.toml | Tweaks weekly-checkin command prompt text. |
| .gemini/commands/url-dump.toml | Updates url-dump command description/prompt text. |
| .gemini/commands/update-knowledge-base.toml | Adds Gemini command entrypoint for update-knowledge-base. |
| .gemini/commands/update-cog.toml | Updates update-cog command description/prompt text. |
| .gemini/commands/team-brief.toml | Adds Gemini command entrypoint for team-brief. |
| .gemini/commands/scout.toml | Adds Gemini command entrypoint for scout. |
| .gemini/commands/publish-to-confluence.toml | Adds Gemini command entrypoint for publish-to-confluence. |
| .gemini/commands/onboarding.toml | Updates onboarding command description. |
| .gemini/commands/meeting-transcript.toml | Adds Gemini command entrypoint for meeting-transcript. |
| .gemini/commands/knowledge-consolidation.toml | Updates knowledge-consolidation command description/prompt text. |
| .gemini/commands/generate-release-notes.toml | Adds Gemini command entrypoint for generate-release-notes. |
| .gemini/commands/generate-prd.toml | Adds Gemini command entrypoint for generate-prd. |
| .gemini/commands/export-open-issues.toml | Adds Gemini command entrypoint for export-open-issues. |
| .gemini/commands/daily-brief.toml | Updates daily-brief command description/prompt text. |
| .gemini/commands/create-user-story.toml | Adds Gemini command entrypoint for create-user-story. |
| .gemini/commands/comprehensive-analysis.toml | Adds Gemini command entrypoint for comprehensive-analysis. |
| .gemini/commands/braindump.toml | Updates braindump command description. |
| .gemini/commands/auto-research.toml | Adds Gemini command entrypoint for auto-research. |
| .claude/skills/weekly-checkin/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/url-dump/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/update-knowledge-base/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/update-cog/SKILL.md | Updates Claude skill frontmatter to metadata-based format. |
| .claude/skills/team-brief/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/scout/SKILL.md | Updates Claude skill frontmatter to metadata-based format. |
| .claude/skills/publish-to-confluence/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/onboarding/SKILL.md | Updates Claude onboarding skill metadata and role pack path reference; adjusts embedded templates. |
| .claude/skills/meeting-transcript/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/generate-release-notes/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/generate-prd/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/export-open-issues/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/daily-brief/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/create-user-story/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/comprehensive-analysis/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/braindump/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude/skills/auto-research/SKILL.md | Updates Claude skill frontmatter to metadata-based format; adjusts embedded templates. |
| .claude-plugin/plugin.json | Bumps plugin version and updates role-pack directory structure path. |
| .agents/skills/update-knowledge-base/SKILL.md | Adds canonical agents skill definition for update-knowledge-base. |
| .agents/skills/update-cog/SKILL.md | Adds canonical agents skill definition for update-cog. |
| .agents/skills/scout/SKILL.md | Adds canonical agents skill definition for scout. |
| .agents/skills/publish-to-confluence/SKILL.md | Adds canonical agents skill definition for publish-to-confluence. |
| .agents/skills/meeting-transcript/SKILL.md | Adds canonical agents skill definition for meeting-transcript. |
| .agents/skills/generate-release-notes/SKILL.md | Adds canonical agents skill definition for generate-release-notes. |
| .agents/skills/generate-prd/SKILL.md | Adds canonical agents skill definition for generate-prd. |
| .agents/skills/export-open-issues/SKILL.md | Adds canonical agents skill definition for export-open-issues. |
| .agents/skills/create-user-story/SKILL.md | Adds canonical agents skill definition for create-user-story. |
| .agents/skills/auto-research/SKILL.md | Adds canonical agents skill definition for auto-research. |
Comments suppressed due to low confidence (1)
.agents/skills/update-knowledge-base/SKILL.md:1
metadata.roles,metadata.integrations, andmetadata.keywordsare encoded as comma-separated scalars, not YAML sequences. If any tooling parses these as lists (or follows agentskills.io expectations for arrays), this will break type assumptions. Recommendation (mandatory if list semantics are required): represent these fields as actual YAML arrays (e.g.,roles: [product-manager, engineering-lead, founder]) to make the schema unambiguous.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -152,7 +155,6 @@ Assess impact on user: | |||
| Create structured briefing document: | |||
|
|
|||
There was a problem hiding this comment.
The generated-document template looks like YAML frontmatter, but it no longer includes --- delimiters. If downstream tooling (or vault conventions) expects real frontmatter for metadata extraction, this template will produce plain text instead of frontmatter. Recommendation (mandatory if frontmatter is required): re-add the opening/closing --- inside the fenced block or explicitly label this as “YAML header (not frontmatter)” and update any consumers accordingly.
Comment on lines
+53
to
+54
| ### 5. Detect Customizations | ||
| Before updating, check if the user has customized any framework files: |
There was a problem hiding this comment.
The text says “compare against the version they originally got,” but git diff cog-upstream/main -- <file> compares the current working tree to upstream, not to the user’s original base version. This can’t distinguish “local customization” vs “upstream changed since installation.” Recommendation (mandatory): either (a) change the wording to match what the command actually does, or (b) compute a merge-base (or equivalent “installed base” ref) and diff against that to detect true local customizations.
| @@ -0,0 +1,351 @@ | |||
| --- | |||
| name: "cog-generate-prd" | |||
| displayName: "COG Generate Prd" | |||
There was a problem hiding this comment.
displayName: "COG Generate Prd" uses inconsistent acronym casing relative to the rest of the content (“PRD”). Recommendation (optional): change to “COG Generate PRD” for consistency and to improve discoverability in UIs that list powers by display name.
Suggested change
| displayName: "COG Generate Prd" | |
| displayName: "COG Generate PRD" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Draft: Single source of truth for skills + cog-sync.sh
Title
Add single source of truth for skills with cross-tool sync (cog-sync.sh)
Body
Summary
Introduces a single-source-of-truth architecture for COG skills. All skills are now authored in
.agents/skills/[name]/SKILL.mdusing the agentskills.io standard, andcog-sync.shgenerates native files for each AI tool.Before: Skills were manually maintained in 3 separate formats (Claude Code, Kiro, Gemini CLI) with 7 of 18 skills missing Kiro and Gemini equivalents.
After: Edit one file, run one script — all 18 skills are available in all tools with full parity.
What changed
New:
.agents/skills/— single source of truthmetadata.roles,metadata.integrations,metadata.keywords,metadata.display-nameNew:
cog-sync.sh— cross-tool sync scriptGenerates native files from
.agents/skills/:.claude/skills/[name]/SKILL.mdCLAUDE.md.gemini/skills/[name].md.tomlcommand entry point.gemini/commands/[name].tomlGEMINI.md.kiro/powers/cog-[name]/POWER.mdFeatures:
--dry-run— preview without writing--check— parity verification (CI-friendly)CLAUDE.mdandGEMINI.mdkeep tool-specific headers above a<!-- AUTO-GENERATED -->marker, withAGENTS.mdcontent appended belowNew:
cog-migrate-skills.sh— one-time migration helperConverts existing
.claude/skills/frontmatter to agentskills.io format:update-cogmaps tocog-update)Full Kiro + Gemini parity (7 → 18 skills)
Previously only 7 core skills had Kiro powers and Gemini commands. Now all 18 skills are generated for every tool:
cog-auto-research,cog-comprehensive-analysis,cog-create-user-story,cog-export-open-issues,cog-generate-prd,cog-generate-release-notes,cog-meeting-transcript,cog-publish-to-confluence,cog-scout,cog-team-brief,cog-update-knowledge-base.kiro/powers/cog-update/→.kiro/powers/cog-update-cog/(matches skill nameupdate-cog)Bug fix: bash
((0++))crashBoth scripts use
set -euo pipefail. The pattern((var++))silently crashes whenvar=0because bash treats0as falsy exit code. All instances replaced withvar=$((var + 1)).Updated docs
scoutto skills table, updated skill count to 18.gitignore: Added.claude/settings.local.jsonFile count
.kiro/powers/cog-update/POWER.md— replaced bycog-update-cog)Test plan
./cog-sync.sh --check— should report 0 issues./cog-sync.sh --dry-run— verify all expected files listed./cog-migrate-skills.sh --dry-run— verify all 18 skills show correct keywords (no(generated keywords)except for truly new skills).claude/skills//onboardingand other/commandswork./cog-sync.shafter deleting a source skill — verify orphan cleanup removes generated filesCLAUDE.mdkeeps its header after sync (integration prefs, role packs, vault structure)GEMINI.mdkeeps its header after sync (vault structure, rules)