docs: refresh contributor documentation

AGENTS.md

@@ -26,7 +26,7 @@ beagle/
     └── beagle-testing/          # Test plan generation and execution (2 skills)
 ```
 
-Each plugin is self-contained with its own `plugin.json` and `skills/` directory.
+Each active plugin is a directory under `plugins/` with its own `README.md` and `skills/` directory. The marketplace manifest at `.claude-plugin/marketplace.json` is the only plugin manifest; individual plugin directories do not have `plugin.json` files.
 
 ## Local Development
 
@@ -45,7 +45,7 @@ Restart Claude Code after changes to reload. Skills are discovered from plugin `
 
 See [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) for the canonical format.
 
-Beagle treats skills as the canonical format. Former command workflows were unified into `SKILL.md` files under each plugin's `skills/` directory, where frontmatter controls user exposure and behavior.
+Beagle treats skills as the canonical format. Former command workflows were unified into `SKILL.md` files under each plugin's `skills/` directory, where frontmatter controls user exposure and behavior. The 10 active marketplace plugins contain 132 canonical `SKILL.md` entry points; the deprecated `beagle-ai` skill files remain on disk for backward compatibility and are not listed in the main catalog.
 
 **Skills** (`plugins/<name>/skills/` folders): Auto-loaded when relevant. Structure: `skill-name/SKILL.md` with optional `references/` folder and frontmatter such as `disable-model-invocation` and `user-invocable`.
 
@@ -106,7 +106,7 @@ Beagle-specific:
 ## Conventions
 
 - **Commits**: Conventional Commits format (feat, fix, docs, refactor, test, chore)
-- **Versioning**: Semantic versioning in marketplace.json and each plugin's `plugin.json`
+- **Versioning**: Semantic versioning in `.claude-plugin/marketplace.json`
 - **Release notes**: Keep a Changelog format, generated via `/beagle-core:gen-release-notes`
 - **Skill references**: Use `<plugin-name>:<skill-name>` format (e.g., `beagle-python:python-code-review`)
 
@@ -117,7 +117,7 @@ This is a pure markdown plugin marketplace. No npm, no build, no tests. Validati
 ## Release Process
 
 1. **Update CHANGELOG.md** - Add new version section with changes (Keep a Changelog format)
-2. **Bump version** - Update `version` in `.claude-plugin/marketplace.json` and affected plugin.json files (semver)
+2. **Bump version** - Update `metadata.version` in `.claude-plugin/marketplace.json` (semver)
 3. **Commit** - `chore(release): bump version to X.Y.Z`
 4. **Push** - `git push origin main`
 5. **Tag** - `git tag -a vX.Y.Z -m "Release vX.Y.Z - Summary"` and `git push origin vX.Y.Z`

CLAUDE.md

@@ -26,7 +26,7 @@ beagle/
     └── beagle-testing/          # Test plan generation and execution (2 skills)
 ```
 
-Each plugin is self-contained with its own `plugin.json` and `skills/` directory.
+Each active plugin is a directory under `plugins/` with its own `README.md` and `skills/` directory. The marketplace manifest at `.claude-plugin/marketplace.json` is the only plugin manifest; individual plugin directories do not have `plugin.json` files.
 
 ## Local Development
 
@@ -47,7 +47,7 @@ See [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills
 
 **Skills** (`plugins/<name>/skills/` folders): Auto-loaded by Claude when relevant. Structure: `skill-name/SKILL.md` with optional `references/` folder and frontmatter such as `disable-model-invocation` and `user-invocable`.
 
-Former command workflows have been unified into the skills format. The 10 active marketplace plugins contain 131 canonical `SKILL.md` entry points; the deprecated `beagle-ai` skill files remain on disk for backward compatibility. No separate plugin `commands/` directories exist under `plugins/`.
+Former command workflows have been unified into the skills format. The 10 active marketplace plugins contain 132 canonical `SKILL.md` entry points; the deprecated `beagle-ai` skill files remain on disk for backward compatibility. No separate plugin `commands/` directories exist under `plugins/`.
 
 ## Creating New Skills
 
@@ -106,7 +106,7 @@ Beagle-specific:
 ## Conventions
 
 - **Commits**: Conventional Commits format (feat, fix, docs, refactor, test, chore)
-- **Versioning**: Semantic versioning in marketplace.json and each plugin's `plugin.json`
+- **Versioning**: Semantic versioning in `.claude-plugin/marketplace.json`
 - **Release notes**: Keep a Changelog format, generated via `/beagle-core:gen-release-notes`
 - **Skill references**: Use `<plugin-name>:<skill-name>` format (e.g., `beagle-python:python-code-review`)
 
@@ -117,7 +117,7 @@ This is a pure markdown plugin marketplace. No npm, no build, no tests. Validati
 ## Release Process
 
 1. **Update CHANGELOG.md** - Add new version section with changes (Keep a Changelog format)
-2. **Bump version** - Update `version` in `.claude-plugin/marketplace.json` and affected plugin.json files (semver)
+2. **Bump version** - Update `metadata.version` in `.claude-plugin/marketplace.json` (semver)
 3. **Commit** - `chore(release): bump version to X.Y.Z`
 4. **Push** - `git push origin main`
 5. **Tag** - `git tag -a vX.Y.Z -m "Release vX.Y.Z - Summary"` and `git push origin vX.Y.Z`

CONTRIBUTING.md

@@ -1,95 +1,126 @@
 # Contributing to Beagle
 
-Contributions are welcome. This guide covers how to add skills, commands, and improvements.
+Contributions are welcome. This guide covers how to add skills and documentation to the Beagle Agent Skills marketplace.
 
 ## Quick start
 
-1. Fork and clone the repository
-2. Create a branch: `git checkout -b feat/my-skill`
-3. Make changes
-4. Test with Claude Code (see below)
-5. Submit a pull request
+1. Fork and clone the repository.
+2. Create a branch: `git checkout -b feat/my-skill`.
+3. Make changes under the relevant `plugins/<plugin>/skills/` directory.
+4. Run the portability check and inspect the changed Markdown.
+5. Submit a pull request.
+
+## Repository layout
+
+Active marketplace plugins live under `plugins/`:
+
+```text
+plugins/<plugin>/
+├── README.md
+└── skills/
+    └── <skill-name>/
+        ├── SKILL.md
+        └── references/      # Optional supporting docs
+```
+
+The marketplace manifest is `.claude-plugin/marketplace.json`. There are no per-plugin `plugin.json` files and no active `commands/` directories; former command workflows were converted to skills.
 
 ## Local development
 
-Add the plugin to `~/.claude/settings.json`:
+Install the whole marketplace for any compatible agent with the skills CLI:
+
+```bash
+npx skills add existential-birds/beagle
+```
+
+During local Claude Code development, add the checkout to `~/.claude/settings.json`:
 
 ```json
 {
   "plugins": ["/path/to/your/beagle"]
 }
 ```
 
-Restart Claude Code after changes to reload.
+Restart the agent after changes so skill discovery reloads. Codex users can link skills from this checkout into `~/.agents/skills/`; see [.codex/INSTALL.md](.codex/INSTALL.md) and [docs/README.codex.md](docs/README.codex.md).
 
 ## Creating skills
 
-Skills are technology knowledge bases in `skills/skill-name/SKILL.md`. See [Agent Skills best practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for authoring guidance.
+Skills are technology knowledge bases in `plugins/<plugin>/skills/<skill-name>/SKILL.md`. See the [Agent Skills specification](https://agentskills.io/specification) and [Agent Skills best practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for authoring guidance.
 
 ### Beagle-specific guidelines
 
-- **Description**: Include trigger keywords (e.g., "React hooks", "FastAPI endpoints")
-- **Content**: Under 500 lines; use `references/` subfolder for additional detail
-- **Focus**: Only include what Claude wouldn't know from training
-- **Code review skills**: Use format `[FILE:LINE] ISSUE_TITLE` for issues
+- **Description**: Include trigger keywords, for example "React hooks" or "FastAPI endpoints".
+- **Content**: Keep `SKILL.md` under 500 lines; use `references/` for details.
+- **Focus**: Include Beagle-specific workflow and current ecosystem details, not generic facts every agent already knows.
+- **Code review skills**: Report issues as `[FILE:LINE] ISSUE_TITLE`.
+- **Portability**: Do not hard-code one harness as the executing agent. Avoid named tool instructions such as `Task tool`, slash-command invocations, and plugin-namespace tokens in active skill content.
+- **References**: If multiple skills need the same verification protocol, prefer relative links to the canonical reference instead of copying large blocks.
 
 ### Structure
 
-```
-skills/my-skill/
-├── SKILL.md           # Required
-└── references/        # Optional
+```text
+plugins/beagle-example/skills/my-skill/
+├── SKILL.md
+└── references/
     └── advanced.md
 ```
 
-## Creating commands
-
-Commands are workflow files in `commands/command-name.md`. See [Slash commands](https://docs.claude.com/en/docs/claude-code/slash-commands) for format details.
-
-### Beagle-specific guidelines
-
-- Start with context gathering (git status, file detection)
-- Load relevant skills based on detected technologies
-- Include output format templates
-- End with verification steps
-
-## Testing
-
-No automated tests. Validate manually:
+## Validation
+
+This repository is a Markdown marketplace, not a buildable package. Use the checks that match your change:
+
+```bash
+./scripts/check-portability.sh
+python3 - <<'PY'
+from pathlib import Path
+import yaml
+for path in Path('plugins').glob('*/skills/*/SKILL.md'):
+    text = path.read_text()
+    if not text.startswith('---'):
+        raise SystemExit(f'missing frontmatter: {path}')
+    end = text.find('\n---', 3)
+    if end == -1:
+        raise SystemExit(f'unclosed frontmatter: {path}')
+    yaml.safe_load(text[3:end])
+print('frontmatter ok')
+PY
+```
 
-1. Check YAML frontmatter is valid
-2. For skills: Start a conversation using trigger keywords
-3. For commands: Run `/beagle:<command-name>`
+For a changed skill, also read it from a fresh agent session or install/link it locally and confirm the trigger description loads the intended workflow.
 
 ## Commits
 
 Use [Conventional Commits](https://www.conventionalcommits.org/):
 
-```
+```text
 feat(skills): add redis-code-review skill
-fix(commands): correct review-python tech detection
+fix(skills): correct review-python tech detection
 docs: update README with new skills
 ```
 
-Types: `feat`, `fix`, `docs`, `refactor`, `chore`
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`.
 
 ## Pull requests
 
-1. Create a feature branch from `main`
-2. Make focused changes (one skill or command per PR)
-3. Update README.md skill/command tables if adding new ones
-4. Submit PR with clear description
+1. Create a feature branch from `main`.
+2. Make focused changes, usually one skill or closely related skill set per PR.
+3. Update the relevant plugin README and [SKILLS.md](SKILLS.md) when adding, removing, or renaming skills.
+4. Include the portability/frontmatter checks you ran in the PR body.
 
 ## What makes a good skill?
 
-- Fills a knowledge gap (recent library versions, non-obvious patterns)
-- Includes working code examples
-- Follows the technology's official conventions
-- Avoids duplicating Claude's existing knowledge
+- Fills a knowledge gap: recent library versions, non-obvious patterns, or project-specific workflow.
+- Includes concrete commands, file paths, output formats, and verification gates.
+- Follows the technology's official conventions.
+- Avoids duplicating generic model knowledge.
+- Separates long reference material into `references/` files.
 
 ## Releasing
 
-Maintainers use internal commands to create releases:
+Maintainers release from `main`:
 
-1. `/release` - Creates a release PR with updated CHANGELOG and version bump
-2. `/release-tag <version>` - After PR is merged, tags and creates GitHub release
+1. Update `CHANGELOG.md` with a Keep a Changelog version section.
+2. Bump `metadata.version` in `.claude-plugin/marketplace.json`.
+3. Commit with `chore(release): X.Y.Z`.
+4. Tag and push: `git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push origin vX.Y.Z`.
+5. Create the GitHub release for the tag.

PRIVACY.md

@@ -2,17 +2,17 @@
 
 _Last updated: May 26, 2026_
 
-Beagle is a [Claude Code](https://claude.com/claude-code) plugin marketplace distributed as Markdown skill files (plus one local helper script for numbering ADRs). It runs entirely inside your local Claude Code session.
+Beagle is an Agent Skills marketplace distributed as static Markdown skill files, plus local helper scripts such as the ADR numbering helper. It runs entirely inside your local coding-agent session.
 
 ## What we collect
 
 Nothing. Beagle does not collect, store, transmit, or sell any personal data. It contains no telemetry, analytics, tracking, or "phone-home" code, and it has no backend servers.
 
 ## How Beagle works
 
-The plugins are static Markdown instructions that Claude Code reads locally. Beagle makes no network requests of its own.
+The plugins are static Markdown instructions that your coding agent reads locally. Beagle makes no network requests of its own.
 
-Some skills instruct Claude Code to use its own built-in tools — for example web search, `git`, or the GitHub CLI (`gh`) — but only when you invoke those skills. Any such activity is performed by Claude Code and the tools you have configured, under your control. That activity is governed by the privacy policies of those tools and services (for example [Anthropic](https://www.anthropic.com/legal/privacy) and [GitHub](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement)), not by Beagle.
+Some skills instruct your agent to use its configured tools — for example web search, `git`, or the GitHub CLI (`gh`) — but only when you invoke those skills. Any such activity is performed by your agent and the tools you have configured, under your control. That activity is governed by the privacy policies of those tools and services, not by Beagle.
 
 ## Your data