optimize-skill

Name: optimize-skill
Author: apache

68stars52forks

How to install optimize-skill?

apache/magpie/optimize-skill

$npx -y skills add apache/magpie --skill optimize-skill

Installs into the current project.

Summary

Optimize an existing framework skill (or sweep a set of them) by applying the restructuring patterns proven on the security-skill suite: split an oversized SKILL.md into linked sibling docs, lift concrete/project-specific values out of the body into <project-config> placehold

Files · 1

View on GitHub

SKILL.md

1	<!-- SPDX-License-Identifier: Apache-2.0
2	https://www.apache.org/licenses/LICENSE-2.0 -->
3
4	<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):
5	<project-config> → adopting project's `.apache-magpie/` directory
6	<tracker> → value of `tracker_repo:` in <project-config>/project.md
7	<upstream> → value of `upstream_repo:` in <project-config>/project.md
8	<framework> → `.apache-magpie/apache-magpie` in adopters; `.` in
9	the framework standalone -->
10
11	# optimize-skill
12
13	Take one existing framework skill — or a maintainer-supplied set of
14	them — and make it leaner without changing what it does. The skill
15	diagnoses a target against the optimization catalogue distilled from
16	the recent security-suite refactors, proposes the applicable passes,
17	and applies them one at a time as behavior-preserving edits the
18	maintainer confirms. The skill validator (and, for tracker-touching
19	skills, the placeholder linter) is the deterministic gate: it is
20	green before the first pass and green again after the last.
21
22	This skill operates only on framework-internal files — `SKILL.md`
23	bodies, their sibling docs, `<project-config>` manifests, tool
24	adapters in this repo. It reads no external or attacker-controlled
25	content, so the prompt-injection-defence callout does not apply.
26
27	It is the refactoring counterpart to
28	[`write-skill`](../write-skill/SKILL.md): `write-skill` authors a
29	net-new skill; `optimize-skill` restructures one that already exists.
30	The five passes, their smells, exemplar PRs, mechanics, and
31	behavior-preservation guarantees live in
32	[`patterns.md`](patterns.md); this body is the orchestration.
33
34	---
35
36	## Adopter overrides
37
38	Before running the default behaviour documented
39	below, this skill consults
40	[`.apache-magpie-local/optimize-skill.md`](../../docs/setup/agentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides/optimize-skill.md`](../../docs/setup/agentic-overrides.md) (committed, project-wide)
41	in the adopter repo if it exists, and applies any
42	agent-readable overrides it finds. See
43	[`docs/setup/agentic-overrides.md`](../../docs/setup/agentic-overrides.md)
44	for the contract — what overrides may contain, hard
45	rules, the reconciliation flow on framework upgrade,
46	upstreaming guidance.
47
48	Hard rule: agents NEVER modify the snapshot under
49	`<adopter-repo>/.apache-magpie/`. Local modifications
50	go in the override file. Framework changes go via PR
51	to `apache/magpie`.
52
53	---
54
55	## Snapshot drift
56
57	Also at the top of every run, this skill compares the
58	gitignored `.apache-magpie.local.lock` (per-machine
59	fetch) against the committed `.apache-magpie.lock`
60	(the project pin). On mismatch the skill surfaces the
61	gap and proposes
62	[`/magpie-setup upgrade`](../setup/upgrade.md).
63	The proposal is non-blocking — the user may defer if
64	they want to run with the local snapshot for now.
65
66	---
67
68	## Inputs
69
70	- Target — the skill to optimize, as a skill name
71	(`security-issue-import`), a directory
72	(`.claude/skills/security-issue-import/`), or a `SKILL.md`
73	path. Required for a single-skill run.
74	- Sweep selector (optional) — `--all` to diagnose every skill
75	under `.claude/skills/` and rank optimization candidates without
76	applying anything, or `over:<N>` to scope the sweep to SKILL.md
77	files longer than `<N>` lines (default threshold: 500, the
78	`PRINCIPLES.md` P14 cap).
79	- Pass filter (optional) — restrict to named pas

People who liked this also viewed

6 picks

Type

optimize-skill

68stars52forks

View on GitHub

How to install optimize-skill?

apache/magpie/optimize-skill

$npx -y skills add apache/magpie --skill optimize-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<!-- SPDX-License-Identifier: Apache-2.0
2	https://www.apache.org/licenses/LICENSE-2.0 -->
3
4	<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):
5	<project-config> → adopting project's `.apache-magpie/` directory
6	<tracker> → value of `tracker_repo:` in <project-config>/project.md
7	<upstream> → value of `upstream_repo:` in <project-config>/project.md
8	<framework> → `.apache-magpie/apache-magpie` in adopters; `.` in
9	the framework standalone -->
10
11	# optimize-skill
12
13	Take one existing framework skill — or a maintainer-supplied set of
14	them — and make it leaner without changing what it does. The skill
15	diagnoses a target against the optimization catalogue distilled from
16	the recent security-suite refactors, proposes the applicable passes,
17	and applies them one at a time as behavior-preserving edits the
18	maintainer confirms. The skill validator (and, for tracker-touching
19	skills, the placeholder linter) is the deterministic gate: it is
20	green before the first pass and green again after the last.
21
22	This skill operates only on framework-internal files — `SKILL.md`
23	bodies, their sibling docs, `<project-config>` manifests, tool
24	adapters in this repo. It reads no external or attacker-controlled
25	content, so the prompt-injection-defence callout does not apply.
26
27	It is the refactoring counterpart to
28	[`write-skill`](../write-skill/SKILL.md): `write-skill` authors a
29	net-new skill; `optimize-skill` restructures one that already exists.
30	The five passes, their smells, exemplar PRs, mechanics, and
31	behavior-preservation guarantees live in
32	[`patterns.md`](patterns.md); this body is the orchestration.
33
34	---
35
36	## Adopter overrides
37
38	Before running the default behaviour documented
39	below, this skill consults
40	[`.apache-magpie-local/optimize-skill.md`](../../docs/setup/agentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides/optimize-skill.md`](../../docs/setup/agentic-overrides.md) (committed, project-wide)
41	in the adopter repo if it exists, and applies any
42	agent-readable overrides it finds. See
43	[`docs/setup/agentic-overrides.md`](../../docs/setup/agentic-overrides.md)
44	for the contract — what overrides may contain, hard
45	rules, the reconciliation flow on framework upgrade,
46	upstreaming guidance.
47
48	Hard rule: agents NEVER modify the snapshot under
49	`<adopter-repo>/.apache-magpie/`. Local modifications
50	go in the override file. Framework changes go via PR
51	to `apache/magpie`.
52
53	---
54
55	## Snapshot drift
56
57	Also at the top of every run, this skill compares the
58	gitignored `.apache-magpie.local.lock` (per-machine
59	fetch) against the committed `.apache-magpie.lock`
60	(the project pin). On mismatch the skill surfaces the
61	gap and proposes
62	[`/magpie-setup upgrade`](../setup/upgrade.md).
63	The proposal is non-blocking — the user may defer if
64	they want to run with the local snapshot for now.
65
66	---
67
68	## Inputs
69
70	- Target — the skill to optimize, as a skill name
71	(`security-issue-import`), a directory
72	(`.claude/skills/security-issue-import/`), or a `SKILL.md`
73	path. Required for a single-skill run.
74	- Sweep selector (optional) — `--all` to diagnose every skill
75	under `.claude/skills/` and rank optimization candidates without
76	applying anything, or `over:<N>` to scope the sweep to SKILL.md
77	files longer than `<N>` lines (default threshold: 500, the
78	`PRINCIPLES.md` P14 cap).
79	- Pass filter (optional) — restrict to named pas

People who liked this also viewed

6 picks

Type