You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/06/28 16:53:25 UTC
(magpie) branch main updated: docs: add "need help -> adopt a family" guide + utilities overview (#600)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new afdce33b docs: add "need help -> adopt a family" guide + utilities overview (#600)
afdce33b is described below
commit afdce33b497d589fdc9e806649d8529204a743a5
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Sun Jun 28 18:53:19 2026 +0200
docs: add "need help -> adopt a family" guide + utilities overview (#600)
- docs/index.md: add a "Need help with one of these? Adopt a family of
skills" section mapping common maintainer pain points to the skill family
that addresses each, linking to the family overviews.
- docs/utilities/README.md: new family overview for the meta-skills
(write-skill, optimize-skill, list-skills), matching the structure of the
other family READMEs.
Gives the apache/magpie website's landing CTAs and family cards a real
overview page to link to for every family.
Generated-by: Claude Opus 4.8 (1M context)
---
docs/index.md | 21 +++++++++++++++
docs/utilities/README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 90 insertions(+)
diff --git a/docs/index.md b/docs/index.md
index 3cdd9a1d..cadb30b6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,6 +4,7 @@
- [What is Apache Magpie?](#what-is-apache-magpie)
- [How it works](#how-it-works)
+ - [Need help with one of these? Adopt a family of skills](#need-help-with-one-of-these-adopt-a-family-of-skills)
- [Who is this for?](#who-is-this-for)
- [Maintainers wanting to adopt Magpie in their project](#maintainers-wanting-to-adopt-magpie-in-their-project)
- [Security team members](#security-team-members)
@@ -41,6 +42,26 @@ Each project picks the modes that fit. You can run just Triage and nothing else.
---
+## Need help with one of these? Adopt a family of skills
+
+Magpie's skills ship in **families**. You don't adopt all of them — you pick the ones that match a problem you actually have today. Each family page explains what it does, which skills it includes, and how to turn it on.
+
+| If you're dealing with… | Adopt the family |
+|---|---|
+| Setting up agents safely — sandbox, clean environment, privacy routing | [setup](setup/README.md) |
+| Security reports that need careful, audited handling | [security](security/README.md) |
+| A pull-request queue that's out of control | [pr-management](pr-management/README.md) |
+| An issue backlog full of duplicates and stale reports | [issue-management](issue-management/README.md) |
+| Repo hygiene slipping — CI runners, dependencies, licenses, flaky tests | [repo-health](repo-health/README.md) |
+| Releases that are a manual, error-prone slog | [release-management](release-management/README.md) |
+| New contributors getting stuck and drifting away | [mentoring](mentoring/README.md) |
+| Growing contributors into committers | [contributor-growth](contributor-growth/README.md) |
+| Building or maintaining your own skills | [utilities](utilities/README.md) |
+
+Start with [`setup`](setup/README.md) regardless — it is the prerequisite every adopter installs first — then add the families above as you need them.
+
+---
+
## Who is this for?
### Maintainers wanting to adopt Magpie in their project
diff --git a/docs/utilities/README.md b/docs/utilities/README.md
new file mode 100644
index 00000000..cb1da8cd
--- /dev/null
+++ b/docs/utilities/README.md
@@ -0,0 +1,69 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Utilities skill family](#utilities-skill-family)
+ - [Skills](#skills)
+ - [When to adopt this family](#when-to-adopt-this-family)
+ - [Adopter contract](#adopter-contract)
+ - [Status](#status)
+ - [Cross-references](#cross-references)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Utilities skill family
+
+Framework meta-skills — the tools you use to **build and maintain skills
+themselves**, rather than to run a maintainership mode on your project. They
+sit outside the MISSION mode taxonomy (Triage, Mentoring, Drafting, Pairing,
+Auto-merge): nothing here acts on your issues, PRs, or contributor threads.
+They are for skill authors and framework contributors.
+
+---
+
+## Skills
+
+| Skill | Purpose | Status |
+|---|---|---|
+| [`write-skill`](../../skills/write-skill/SKILL.md) | Author a new framework skill or update an existing one: frontmatter, placeholder convention, injection defenses, Privacy-LLM gate-check, and validator sign-off. | stable |
+| [`optimize-skill`](../../skills/optimize-skill/SKILL.md) | Optimize an existing skill by applying restructuring patterns — split an oversized `SKILL.md` into linked sibling docs, trim frontmatter, and improve eval alignment. | stable |
+| [`list-skills`](../../skills/list-skills/SKILL.md) | Print a live index of every skill in this repository, grouped by family, with each skill's name and first-sentence description. | stable |
+
+---
+
+## When to adopt this family
+
+Adopt `utilities` if you intend to **write or maintain your own skills** —
+whether contributing them back to Magpie or keeping them in your own project.
+If you are only adopting existing skills to run on your project, you do not
+need this family; the [`setup`](../setup/README.md) family is your starting
+point instead.
+
+---
+
+## Adopter contract
+
+The utilities skills have no project-specific config files and make no state
+changes to your project's tracker, label set, or shared infrastructure.
+`list-skills` and `optimize-skill` are read-only; `write-skill` only creates or
+edits skill files under your control, which you review before committing.
+
+---
+
+## Status
+
+**Stable.** All three skills are shipped and validate under
+`skill-and-tool-validate`. They are framework-authoring tools, so they evolve
+with the framework's own conventions rather than with adopter pilots.
+
+---
+
+## Cross-references
+
+- [`docs/modes.md` § Outside the modes](../modes.md#outside-the-modes) — why
+ these skills sit outside the maintainership-mode taxonomy.
+- [`docs/spec-driven-development.md`](../spec-driven-development.md) — the
+ authoring loop `write-skill` and `optimize-skill` support.