docs(skill): split CGS app-dev skill into router + references

[aspiers]

Summary

Restructure the app-development-with-cgs skill from a single SKILL.md into a lean router plus reference files under references/, and add one covering how to check and interpret a deployment's version. No service code touched.

• SKILL.md becomes the router: auth-mode decision, a dispatch table to the reference files, an error→cause map, and a demo pointer.
• Topic detail moves into references/*.md (proxy-and-records, targeting, group-lifecycle, members-and-roles, cross-group, api-keys, versioning).
• Deduped against docs/: the skill now owns only decisions, traps, and small stable tables; canonical request shapes and long-form prose stay in docs/ and are linked (anchors verified). Removes the paraphrase duplication that would otherwise drift.
• New references/versioning.md answers "what version is this deployment running" (GET /health) and what the number means for an integrator: semver, the pre-1.0 caveat that a minor bump may break the API, and where the release notes live. Notes that production (groups.certified.app) doesn't expose the version endpoint yet.
• Preserves the permission-sets (include:) documentation that landed on main in parallel, folded into references/api-keys.md.

Not in this PR

The Instatus maintenance-scheduling skill that was briefly part of this branch has moved to its canonical cross-service home in certified-infra (hypercerts-org/certified-infra#2). The ePDS copy is being removed in hypercerts-org/ePDS#180.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Warning

Review limit reached

@aspiers, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 13 minutes and 37 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7c8d69e1-372c-4f51-9476-15abffaa90d7

📥 Commits

Reviewing files that changed from the base of the PR and between 9d980f8 and c7983e8.

📒 Files selected for processing (8)

• .agents/skills/app-development-with-cgs/SKILL.md
• .agents/skills/app-development-with-cgs/references/api-keys.md
• .agents/skills/app-development-with-cgs/references/cross-group.md
• .agents/skills/app-development-with-cgs/references/group-lifecycle.md
• .agents/skills/app-development-with-cgs/references/members-and-roles.md
• .agents/skills/app-development-with-cgs/references/proxy-and-records.md
• .agents/skills/app-development-with-cgs/references/targeting.md
• .agents/skills/app-development-with-cgs/references/versioning.md

📝 Walkthrough

Walkthrough

SKILL.md for CGS app development is rewritten as a lightweight router pointing to six new reference documents covering targeting, proxy wiring, API keys, group lifecycle, members/roles, cross-group queries, and versioning. A new scheduling skill is added for Instatus maintenance windows, and .mcp.json introduces MCP server entries for instatus and linear.

Changes

CGS App-Development Skill Restructure

Layer / File(s)	Summary
SKILL.md rewritten as auth-mode router .agents/skills/app-development-with-cgs/SKILL.md	Condensed to a decision guide with the service-auth JWT vs API-key choice, a task-to-reference mapping table, error signals for wrong decisions, and a pointer to the demo/ app; all previously inlined step-by-step content removed.
Targeting and proxy-wiring reference docs .agents/skills/app-development-with-cgs/references/targeting.md, .../proxy-and-records.md	New files document repo placement rules and aud invariant for request targeting, and how to wire the atproto-proxy header flow including the correct proxy target, required NSIDs, and why reads must bypass CGS.
API-keys reference doc .agents/skills/app-development-with-cgs/references/api-keys.md	New file covers when to use API keys vs JWTs, bearer format and key lifecycle, include:<nsid> permission-set behavior with current keys.create limitation, and the querystring repo requirement with error outcomes.
Group domain and versioning reference docs .agents/skills/app-development-with-cgs/references/group-lifecycle.md, .../members-and-roles.md, .../cross-group.md, .../versioning.md	Four new files cover group register/import/destroy semantics, RBAC constraints and audit log behavior, the cross-group membership list endpoint, and how to read and interpret the CGS deployment version.

Instatus Maintenance Scheduling Skill

Layer / File(s)	Summary
MCP server configuration .mcp.json	New file defines mcpServers with entries for instatus (npx-launched, direct tools enabled) and linear (HTTP endpoint).
Scheduling skill: rules, IDs, and message templates .agents/skills/scheduling-instatus-maintenance/SKILL.md (lines 1–107)	Establishes golden rules (draft-first, UTC timestamps, no API key exposure), defines Certified Instatus page ID and component IDs for staging and production, sets 60-minute scheduling defaults, and provides title/message templates for upgrades and reconfiguration.
Scheduling skill: draft format, payload, completion, and fallback .agents/skills/scheduling-instatus-maintenance/SKILL.md (lines 107–240)	Defines the draft format shown before scheduling, the full scheduling payload shape with expandAt behavior, the maintenance-update-based completion flow with verification criteria, and a direct API fallback procedure.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• hypercerts-org/certified-group-service#28: The new references/api-keys.md is directly grounded in the same API-key design concepts (key format, lifecycle/revocation, headers, scope/permissions semantics) as the docs/design/api-keys.md introduced in that PR.
• hypercerts-org/certified-group-service#51: The new references/api-keys.md content and SKILL routing cover the same include:<nsid> API-key permission-set behavior and limitations introduced in that PR.

Suggested reviewers

• pheuberger
• bitbeckers
• s-adamantine

Poem

🐇 Hop through the docs, no more maze to roam,
A router now points to each reference home.
Maintenance windows, all drafted with care,
Instatus and Linear float through the air.
The rabbit says: "Six new guides, neatly linked—
The warren is tidy, not tangled or kinked!" 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: restructuring the CGS app-dev skill by splitting the monolithic SKILL.md into a router pattern with separate reference files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/cgs-app-dev-skill-split

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

.agents/skills/scheduling-instatus-maintenance/SKILL.md (1)

162-168: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Clarify expandAt calculation with a concrete example.

Line 162 shows expandAt using the same placeholder format as start, but lines 166–168 note the actual value should be three days earlier. An implementer might copy the example timestamp directly without calculating the offset, causing the maintenance window to not expand at the intended time.

Suggest adding a concrete example calculation, such as:

{
  "start": "2026-07-15T14:00:00.000Z",
  "expandAt": "2026-07-12T14:00:00.000Z"
}

This makes it clear that expandAt should be exactly 72 hours (3 days) before the start time.

💡 Proposed fix for clarity

 Set `expandAt` to three days before `start` when following recent scheduled
 window style. In the sample above, `expandAt` uses the same timestamp format as
-`start` / `end`, but the actual value should be three days earlier.
+`start` / `end`. For example, if `start` is `2026-07-15T14:00:00.000Z`, set
+`expandAt` to `2026-07-12T14:00:00.000Z` (exactly 72 hours earlier).

Optionally, update the example payload to show both timestamps with the correct offset:

   "start": "YYYY-MM-DDTHH:mm:ss.000Z",
   "end": "YYYY-MM-DDTHH:mm:ss.000Z",
   ...
-  "expandAt": "YYYY-MM-DDTHH:mm:ss.000Z"
+  "expandAt": "YYYY-MM-DDTHH:mm:ss.000Z"  /* 3 days before 'start' */

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.agents/skills/scheduling-instatus-maintenance/SKILL.md around lines 162 -
168, The JSON example showing the `expandAt` field uses the same placeholder
format as `start` without demonstrating the actual 3-day offset calculation,
which could lead implementers to copy the example directly without the proper
offset. Replace the generic `expandAt` placeholder value in the example with a
concrete timestamp that is exactly 72 hours before the `start` timestamp shown
in the same example, making the 3-day offset calculation explicit and clear to
readers.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.agents/skills/scheduling-instatus-maintenance/SKILL.md:
- Around line 162-168: The JSON example showing the `expandAt` field uses the
same placeholder format as `start` without demonstrating the actual 3-day offset
calculation, which could lead implementers to copy the example directly without
the proper offset. Replace the generic `expandAt` placeholder value in the
example with a concrete timestamp that is exactly 72 hours before the `start`
timestamp shown in the same example, making the 3-day offset calculation
explicit and clear to readers.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dce0c0c4-bf73-4d2a-b90b-5103d832973b

📥 Commits

Reviewing files that changed from the base of the PR and between 29f4b48 and 9d980f8.

📒 Files selected for processing (10)

• .agents/skills/app-development-with-cgs/SKILL.md
• .agents/skills/app-development-with-cgs/references/api-keys.md
• .agents/skills/app-development-with-cgs/references/cross-group.md
• .agents/skills/app-development-with-cgs/references/group-lifecycle.md
• .agents/skills/app-development-with-cgs/references/members-and-roles.md
• .agents/skills/app-development-with-cgs/references/proxy-and-records.md
• .agents/skills/app-development-with-cgs/references/targeting.md
• .agents/skills/app-development-with-cgs/references/versioning.md
• .agents/skills/scheduling-instatus-maintenance/SKILL.md
• .mcp.json

[aspiers]

Addressed the expandAt nitpick in d3ac0e5 — added a concrete worked example (start 2026-07-15T14:00:00.000Z → expandAt 2026-07-12T14:00:00.000Z, 72h earlier) and a warning against copying the start timestamp. Thanks @coderabbitai.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@aspiers That's a great improvement — the concrete timestamp pair and the explicit "don't copy start" warning make the intent unambiguous. Thanks for the quick follow-up!

(∧ ･ ᴥ ･ ∧)

---

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!

[railway-app]

🚅 Deployed to the certified-group-service-pr-55 environment in CGS

Service	Status	Web	Updated (UTC)
certified-group-service	✅ Success (View Logs)	Web	Jun 23, 2026 at 4:46 pm
CGS demo app	✅ Success (View Logs)	Web	Jun 23, 2026 at 4:44 pm

[aspiers]

@coderabbitai the expandAt nitpick targets .agents/skills/scheduling-instatus-maintenance/SKILL.md, which is no longer part of this PR — the scheduling skill has been removed from this branch and moved to certified-infra (hypercerts-org/certified-infra#2), where the concrete expandAt example you suggested is already applied. This PR is now the app-dev skill split only, so there's nothing to change here.