y-miyazakiy-miyazaki/config/.apm/CLAUDE.md

config

CLAUDE.md1 starsChanged 8 days agoApache-2.0View on GitHub

Rules for authoring under .apm/packages/**. Package sources are distribution artifacts — apm install copies them into this repository and into consumer repositories. Edit targets and sync: CLAUDE.md § Edit routing. Design depth: apm-package-design.md. If a sentence applies only in this repository, it does not belong in a package source. Normative rules for all skills under .apm/packages/**. Design depth: apm-package-design.md § Skill authoring.

In this repository56 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/workflows/CLAUDE.mdCLAUDE.md
- .cursor/rules/agent-skills.mdcCursor rule
- .cursor/rules/bats.mdcCursor rule
- .cursor/rules/github-actions-workflow.mdcCursor rule
- .cursor/rules/go.mdcCursor rule
- .cursor/rules/go-test.mdcCursor rule
- .cursor/rules/instructions.mdcCursor rule
- .cursor/rules/markdown.mdcCursor rule
- .cursor/rules/shell-script.mdcCursor rule
- .cursor/rules/terraform.mdcCursor rule
- agent-skills-reviewSkill
- changelogSkill
- ci-sweeperSkill
- docs-creatorSkill
- docs-updaterSkill
- github-actions-reviewSkill
- github-actions-validationSkill
- github-issue-autofixSkill
- github-issue-triageSkill
- github-pr-bodySkill
- github-pr-reviewSkill
- github-pr-reviseSkill
- go-reviewSkill
- go-validationSkill
- instructions-reviewSkill
- loop-verifierSkill
- markdown-validationSkill
- refactorSkill
- shell-script-reviewSkill
- shell-script-validationSkill
- tech-debtSkill
- test-gapSkill
- agent-skills-reviewSkill
- changelogSkill
- ci-sweeperSkill
- docs-creatorSkill
- docs-updaterSkill
- github-actions-reviewSkill
- github-actions-validationSkill
- github-issue-autofixSkill
- github-issue-triageSkill
- github-pr-bodySkill
- github-pr-reviewSkill
- github-pr-reviseSkill
- go-reviewSkill
- go-validationSkill
- instructions-reviewSkill
- loop-verifierSkill
- markdown-validationSkill
- refactorSkill
- shell-script-reviewSkill
- shell-script-validationSkill
- tech-debtSkill
- test-gapSkill

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
If a sentence applies only in this repository, it does not belong in a package source.
line 19
Distinctive:
Place new skills by forge/runtime, never by “this is a loop skill”:
line 42

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

CLAUDE.md

Rules for authoring under .apm/packages/**. Package sources are distribution artifacts — apm install copies them into this repository and into consumer repositories.

Edit targets and sync: CLAUDE.md § Edit routing. Design depth: apm-package-design.md.

Distributable vs maintainer-only (MUST)

Write in `.apm/packages/**`	Write in maintainer docs instead (`CLAUDE.md`, this file, `docs/`)
Portable contracts any consumer can follow	This repository's paths, CI, sync scripts, Loop caller/action names
In-skill relative paths (`scripts/`, `references/`, `assets/`)	`apm install` / `sync_*` as normative user steps
Stem-based companion cross-links	Repo-specific `validate_`, Bats `assert_`, `scripts/lib/` paths in redistributable `references/`
Behavior that does not assume this layout	Fixed universal directory mandates (`test/bats/` only, `docs/report/…` required)
	`agent_edit_allowed` / automation envelope for this consumer — see loop-pr-body-skill-contract

If a sentence applies only in this repository, it does not belong in a package source.

Skill design (MUST)

Normative rules for all skills under .apm/packages/**. Design depth: apm-package-design.md § Skill authoring.

Rule	Requirement
Self-contained interactive path	MUST run from user prompt + in-skill `references/` without requiring sibling skills, loop callers, or detect scripts
Optional automation assets	Detect scripts and `hints[]` JSON are optional caller inputs — document them as hints, not prerequisites
Consumer context wins	Repository norms (testing, lint, paths, security) live in consumer `AGENTS.md`, steering rules, and user prompt — MUST NOT embed repo-specific principles in package `references/`
No other skill prerequisites	MUST NOT treat any other skill as a required prerequisite for interactive execution; optional routing via session `## Instructions` or consumer context does not create a hard dependency
Portable scope only	Path scope in skills: user allowlist/denylist, automation `## Constraints`, and portable skill limits — MUST NOT document ambient tool behavior (ignore files, default VCS exclusions)
Portable verification	Describe gate procedure (run what the repo already uses) — MUST NOT embed language/stack command tables in distributable `references/`

Violations are blocking portability defects on package PRs — same severity as DIST table rows below.

Design comparison (SHOULD): when deciding how a skill is written (edit gates, structure, rule style), compare with well-known external skills — for example the official plugin skills skill-creator, claude-md-improver, and plugin-dev skill-development — and record the comparison in the proposal or PR. Prefer an intent-level rule with its reason over enumerations or stacked MUSTs, as those skills do.

Package placement (MUST)

Place new skills by forge/runtime, never by “this is a loop skill”:

If the skill requires	Package
No forge API; in-repo files	`repo-maintenance`
GitHub Issue/PR / `gh`	`github`
GitHub Actions YAML only	`github-actions`
Generic loop checker (not a domain)	`loop`
Review/markdown/docs authoring with no forge	`common`
Language stack	`go` / `shell-script` / `terraform`

Loop-capable skills (Interactive + Automation) are a family. Cross-cutting envelope, report shape, description triggers, and detect JSON changes MUST follow Loop-Capable Skills — do not patch a single loop entry skill’s shared contract in isolation.

YAML description on those skills MUST mention conversation use first or equally with automation; MUST NOT read as workflow-only.

Loop PR body skills (MUST)

Applies to skills that ship references/category-pr-body-links.md (changelog, ci-sweeper, docs-updater, refactor, tech-debt, test-gap, github-issue-autofix, github-pr-revise). Contract depth: loop-pr-body-skill-contract. Enforced by scripts/self/apm/check_loop_pr_body_contract.sh (runs in sync_apm_artifacts.sh loop-contract and Bats).

Rule	Requirement
Reference guide	`SKILL.md` MUST list `references/category-pr-body-links.md`, `assets/pr-body-template.md`, and `assets/pr-body-template-survey.md` in its reference guide — an agent only follows what `SKILL.md` names
Link everything	Repository paths, commit SHAs, and workflow/job targets in Summary and Verification are markdown links per that skill's `category-pr-body-links.md`; a code span is not a link
Template placeholders	Templates and `common-output-format.md` mark linkable items with `<linked path>`, `<linked sha>`, `<linked workflow>`, `<linked job>` — MUST NOT* use a backtick path or an example `org/repo` link
Template rules block	Each template's leading comment carries the link rule and `Keep the table columns as written` — columns are not renamed, merged, or dropped (docs-updater's one-item bullet exception stays)
Format is not a gate	Link and column drift is steered by the above, not by `validate_agent_report.sh` REJECT — a cosmetic miss must not cost a maker retry
Platform safety net	`loop-finalize` (`linkify_agent_text`) links changed-file paths and detected SHAs the agent left unlinked. Maintainer-only: package sources MUST NOT rely on it or mention it

Comment-posting skills (github-issue-triage, github-pr-review) have no PR body template, but their comment/review text carries the same links: each ships references/category-pr-body-links.md (the file name is shared across loop skills; here it covers comment and review text) and lists it in SKILL.md. github-pr-review pins line links to a full commit SHA; github-issue-triage links #N, commits, and existing paths.

Adding a loop skill that ships category-pr-body-links.md means adding it to LOOP_PR_BODY_LINKS_SKILLS (PR body skills) or LOOP_COMMENT_LINKS_SKILLS (comment-posting skills) in the checker.

Redistribution (DIST) — maintainer judgment

Enforce via PR review and this file. Not an agent-skills-review or instructions-review ItemID — those skills run in external repos and must stay generalized.

In package sources	Judgment
MUST NOT embed	Config-repo paths/trees, internal automation names, maintainer CLI as required steps, Loop platform names for this consumer, single canonical paths for all consumers, large eval corpora in the skill tree
SHOULD use	Portable checklist contracts, in-skill paths, stem cross-links, stable `https://` references
Local-only skills in a consumer repo	Repo-specific rules live in that repo's `AGENTS.md` / `docs/` — not in redistributable package sources

Review skills (agent-skills-review, instructions-review) MUST encode generalized checks only.

Release bar (this repository only)

Rule	Requirement
Mock eval	Verifies contract structure — not production behavior.
Behavior	MUST be covered by `test/bats/`, `scripts/*/validate.sh`, and/or real executor / `waza run --baseline` in this repo.
Ship decision	Mock eval green + repo CI green before releasing skills from this repository.
Eval packaging	SHOULD keep a thin harness (`eval.yaml`, task YAMLs); avoid large corpora inside distributable skill trees (E-01 / E-03 — maintainer judgment, not review ItemIDs).
Eval naming	MUST name task files `evals/tasks/<skill-name>-<scenario>.yaml`, and start task `id` with `<skill-name>-`.
Eval contract	Mock executor echoes the prompt, so mock green does not prove graders match the output contract. Before release, run a real executor (`waza run --baseline`) when SKILL.md or `common-output-format.md` changes, and keep grader strings inside that skill's output contract.

Validation scripts mirror (MUST)

Edit repo scripts/<domain>/ only — do not hand-edit skill copies. Transforms: sync_validate_mirror.sh.

Domain	Mirrored files
`shell-script`	`validate.sh`, `fix_function_doc_order.sh`
`go`, `terraform`	`validate.sh`

Path layout differs only in library import lines and WORKSPACE_ROOT depth for shell-script validate.sh — see sync_validate_mirror.sh and CLAUDE.md § Edit routing.

Pointers (not rules)

Topic	Document
Skill self-containment (all skills)	This file — § Skill design (MUST)
Skill vs product, automation envelope	apm-package-design.md
Loop PR body rules (links, templates)	This file — § Loop PR body skills (MUST)
Instruction sync	instructions-sync-workflow.md
Loop platform (this consumer)	Loop Engineering
SKILL authoring stems	companion `agent-skills` rules; `agent-skills-review` skill

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free