Add portable AI source folder READMEs

[ashleyshaw]

General Pull Request

This repository enforces changelog, release, and label automation for all PRs.
See the organisation-wide Automation Governance & Release Strategy for contributor rules.

Linked issues

Closes #290

Changelog

Added

• Added ownership and migration README files for the new portable AI source folders:
  .schemas/, agents/, cookbook/, hooks/, instructions/, plugins/, skills/, and workflows/.
• Added folder-level guidance covering ownership, structure, usage, validation, and migration rules for portable AI assets.
• Added a new Portable AI Source Folders index to the root README.md.

Changed

• Updated the root README.md last_updated date to 2026-05-18.
• Standardised documentation for where portable schemas, agents, recipes, hooks, instructions, plugins, skills, and workflows should live.
• Documented migration boundaries between portable top-level folders and existing .github/* paths.

Fixed

• Reduced ambiguity around where reusable AI assets should be created and how they should be migrated out of repo-specific .github locations.

Removed

• None.

---

Risk Assessment

Risk Level: Low

Potential Impact:

This is a documentation-only change. If incorrect, the main risk is contributor confusion about folder ownership, migration targets, or where new portable AI assets should be added.

Mitigation Steps:

• Kept the change scoped to README files and root documentation only.
• Added explicit per-folder structure and migration rules rather than broad guidance in a single document.
• Included validation commands in each new README to support consistent review.
• Left repo-specific GitHub-native assets in existing .github/* paths unless explicitly migrated.

---

How to Test

Prerequisites

• Check out PR Add portable AI source folder READMEs #323 locally.

Test Steps

1. Open the root README.md and confirm the new Portable AI Source Folders section is present.
2. Verify each linked folder README exists and matches the linked path:
   • .schemas/README.md
   • agents/README.md
   • cookbook/README.md
   • hooks/README.md
   • instructions/README.md
   • plugins/README.md
   • skills/README.md
   • workflows/README.md
3. Review each README and confirm it includes:
   • overview
   • ownership
   • structure
   • usage
   • validation
   • migration rules
   • related documentation
4. Run Markdown linting against the changed files, for example:

   npx markdownlint-cli2 "README.md" ".schemas/README.md" "agents/README.md" "cookbook/README.md" "hooks/README.md" "instructions/README.md" "plugins/README.md" "skills/README.md" "workflows/README.md"

Expected Results

• The root README includes a clear index for portable AI source folders.
• All eight new folder READMEs are present and internally consistent.
• The guidance clearly distinguishes portable top-level folders from repo-specific .github/* locations.
• Markdown linting passes for all changed documentation files.

Edge Cases to Verify

• Root README links resolve correctly
• No README instructs contributors to move GitHub Actions out of .github/workflows/
• No README treats repo-maintenance-only assets as portable by default
• Validation commands reference the correct file paths
• Migration guidance consistently references tracked migration work

---

Checklist (Global DoD / PR)

• All AC met and demonstrated
• Tests added/updated (unit/E2E as appropriate)
• A11y considerations addressed where relevant
• Docs/readme/changelog updated (if user-facing)
• Security/perf impact reviewed where relevant
• Code/design reviews approved
• CI green; linked issues closed; release notes prepared (if shipping)
• Risk assessment completed above
• Testing instructions provided above

---

References

• Issue #290: Add ownership indexes for new top-level folders
• Portable AI plugin restructure PRD
• Contribution Guidelines
• Branching Strategy
• Automation Governance
• PR Labels

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (5)

• main
• develop
• feature/*
• fix/*
• update/*

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 3edecf7e-44a0-44a1-a245-fa4598911231

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Note

.coderabbit.yml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'auto_labels', 'auto_assign', 'auto_review'

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/290-folder-ownership-indexes

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request establishes a new top-level directory structure for portable AI assets, including schemas, agents, cookbooks, hooks, instructions, plugins, skills, and workflows. Each directory now contains a README defining its purpose, ownership, and migration rules from the legacy .github folder. Review feedback focused on improving the consistency and clarity of these structures by suggesting standardized entry point filenames (e.g., AGENT.md, hook.sh, workflow.yml) and recommending the removal of GitHub-specific subfolders for plugin manifests to better align with the goal of portability.

[Copilot]

Pull request overview

This PR adds a set of top-level “portable AI source folder” READMEs to standardise ownership, structure, validation, and migration guidance for assets intended to live outside .github/, and updates the root README to index them.

Changes:

• Added new folder-level READMEs for portable .schemas/, agents/, cookbook/, hooks/, instructions/, plugins/, skills/, and workflows/.
• Updated the root README.md last_updated date and added a “Portable AI Source Folders” index linking to the new READMEs.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
README.md	Updates last_updated and adds a new index section linking to the portable folder READMEs.
.schemas/README.md	Defines ownership/usage/migration guidance for portable schemas.
agents/README.md	Defines ownership/usage/migration guidance for portable agent specifications.
cookbook/README.md	Defines ownership/usage/migration guidance for portable recipes/examples.
hooks/README.md	Defines ownership/usage/migration guidance for portable hooks/guardrails.
instructions/README.md	Defines ownership/usage/migration guidance for portable instructions (tool-agnostic).
plugins/README.md	Defines ownership/usage/migration guidance for installable plugin bundles.
skills/README.md	Defines ownership/usage/migration guidance for self-contained skills.
workflows/README.md	Defines ownership/usage/migration guidance for portable agentic workflows (distinct from GitHub Actions).