setup
Scaffolds principle-anchoring configuration for a project. Writes docs/agents/principles.md, adds a `### Principles` block to `## Agent skills` in CLAUDE.md or AGENTS.md, and optionally drafts hook integration snippets for settings.json or tool-routing. Run once per project befor
Install
npx skills add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/stay-principled/skills/setup
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install technicalpickles-pickled-claude-plugins@llmmart
git clone https://github.com/technicalpickles/pickled-claude-plugins.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole technicalpickles/pickled-claude-plugins collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Setup Principles
Scaffold the per-project configuration that stay-principled:grill reads. This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
Process
1. Explore
Look at the current repo to understand its starting state. Read whatever exists; don't assume:
docs/principles.md,docs/ops-principles.md, any sibling*principles*.mdfiles at the repo root or underdocs/docs/agents/principles.md: existing config; update in place if foundCLAUDE.md(preferred) orAGENTS.mdat the repo root: does either exist? Is there already an## Agent skillssection?claude plugin list --json: istool-routinginstalled and enabled? (Affects whether Pattern C is offered.)git rev-parse --show-toplevel: used as the canonical repo root for path resolution; principles inside worktrees still live at the worktree root.
2. Present findings and ask
Summarize what's present and what's missing. Then walk the user through the four sections one at a time. Present a section, get the user's answer, then move to the next. Don't dump all sections at once.
Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why this skill needs it, what changes if they pick differently).
Section A: Where do principles live?
Explainer: The
stay-principled:grillskill needs to know which markdown files contain your principles. Most projects have one (docs/principles.md); some split into multiple (e.g. engineering vs ops). The skill reads all of them at session start to build a working set.
Default posture: if any *principles*.md files were found during exploration, list them and ask the user to confirm or adjust. Multi-file is fine. If none were found, ask the user where their principles are documented (or if they don't yet exist; in that case, suggest creating docs/principles.md and offer to scaffold a starter file before continuing).
Section B: Format hint.
Explainer: This is a free-form description of how the principles are structured in your file. The skill uses this to reason about cross-references, correction cases, and domain-specific sections. The format is not a schema (the skill is format-tolerant) but a description helps it reason better.
Default detection: skim the first 50 lines of the principles file. If it has numbered cross-cutting principles with bold names, "Why:" and "Where:" sections, propose:
"Numbered cross-cutting principles with bold name, statement, Why:, and Where: sections. Domain-specific principles under
## Domain-specific principles. Cross-references between principles by number. Correction cases embedded inWhere:sections."
If the format is simpler (bullets, plain headers), describe what you see and let the user adjust.
Section C: Domain map (optional).
Explainer: Some principles only apply to specific subsystems (e.g. PRM, Tasks). The domain map tells the skill which directories trigger which principle subsets, so it can pull in domain-specific principles when the topic is in a named domain.
If the principles file has a ## Domain-specific principles section (or similar), propose a mapping by reading the section headings and looking for matching directories under src/ or similar. Otherwise skip this section entirely.
Section D: Hook integration (optional, opt-in).
Explainer: By default, you invoke
stay-principled:grillmanually. Hook integration makes other skills (typicallysuperpowers:brainstorming) suggest grilling first when this project has principles configured. Three patterns are available; pick zero, one, or multiple.
Present the three patterns. The user can decline all of them; the runtime skill works fine without integration.
- Pattern A: CLAUDE.md prose. Soft, model-driven. A line added to CLAUDE.md telling the model to consider grilling first.
- Pattern B: Hook helper. Hard, deterministic. A
settings.jsonsnippet that firesskill-adviceon everysuperpowers:brainstorminginvocation. - Pattern C: tool-routing rule. Hard, deterministic. Only offered if
tool-routingis installed.
For each chosen pattern, draft the snippet. See the project docs/integration-patterns.md for the templates.
3. Draft and confirm
Show the user a draft of:
- The contents of
docs/agents/principles.md - The
### Principlesblock to add to whichever ofCLAUDE.md/AGENTS.mdis being edited - Pattern A snippet (if chosen): appended to CLAUDE.md as a routing line
- Pattern B snippet (if chosen): printed for paste into
settings.json. Do not auto-writesettings.json. - Pattern C snippet (if chosen): printed for paste into a tool-routing routes file. Do not auto-write.
Let the user edit before writing.
4. Write
Pick the file to edit:
- If
CLAUDE.mdexists, edit it. - Else if
AGENTS.mdexists, edit it. - If neither exists, ask the user which one to create. Don't pick for them.
Never create AGENTS.md when CLAUDE.md already exists (or vice versa). Always edit the one that's already there.
If an ## Agent skills block already exists, add the ### Principles subsection in-place. Don't append a duplicate. Don't overwrite user edits to surrounding sections.
The block:
## Agent skills
### Principles
[one-line summary of where principles live]. See `docs/agents/principles.md` for format and configuration. The `stay-principled:grill` skill reads from these files.
Then write docs/agents/principles.md using this template, replacing the file's content if it already exists:
# Principles configuration
## Files
- [path to first principles file]
- [path to second, if any]
## Format
[user-confirmed format description from Section B]
## Domain map
[domain to directory mappings from Section C, or omit if skipped]
## Skip patterns
[branch-name or path patterns where principle anchoring should be skipped, or omit]
Pattern A/B/C snippets: write Pattern A inline into CLAUDE.md (append a routing line at the end of the agent-skills block). Print Pattern B and Pattern C snippets for the user to paste manually.
5. Done
Tell the user:
- Setup is complete.
- Which files were written.
- That
stay-principled:grillwill now read fromdocs/agents/principles.md. - That re-running this skill is only needed if the file layout changes; manual edits to
docs/agents/principles.mdare fine.
If integration patterns were offered, remind the user to paste any Pattern B/C snippets into the appropriate config file.
Files (pickled-claude-plugins)
-
SKILL.md 6.9 KB
--- name: setup description: Scaffolds principle-anchoring configuration for a project. Writes docs/agents/principles.md, adds a `### Principles` block to `## Agent skills` in CLAUDE.md or AGENTS.md, and optionally drafts hook integration snippets for settings.json or tool-routing. Run once per project before using stay-principled:grill. Re-run only if the principles file layout changes. disable-model-invocation: true --- # Setup Principles Scaffold the per-project configuration that `stay-principled:grill` reads. This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write. ## Process ### 1. Explore Look at the current repo to understand its starting state. Read whatever exists; don't assume: - `docs/principles.md`, `docs/ops-principles.md`, any sibling `*principles*.md` files at the repo root or under `docs/` - `docs/agents/principles.md`: existing config; update in place if found - `CLAUDE.md` (preferred) or `AGENTS.md` at the repo root: does either exist? Is there already an `## Agent skills` section? - `claude plugin list --json`: is `tool-routing` installed and enabled? (Affects whether Pattern C is offered.) - `git rev-parse --show-toplevel`: used as the canonical repo root for path resolution; principles inside worktrees still live at the worktree root. ### 2. Present findings and ask Summarize what's present and what's missing. Then walk the user through the four sections **one at a time**. Present a section, get the user's answer, then move to the next. Don't dump all sections at once. Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why this skill needs it, what changes if they pick differently). **Section A: Where do principles live?** > Explainer: The `stay-principled:grill` skill needs to know which markdown files contain your principles. Most projects have one (`docs/principles.md`); some split into multiple (e.g. engineering vs ops). The skill reads all of them at session start to build a working set. Default posture: if any `*principles*.md` files were found during exploration, list them and ask the user to confirm or adjust. Multi-file is fine. If none were found, ask the user where their principles are documented (or if they don't yet exist; in that case, suggest creating `docs/principles.md` and offer to scaffold a starter file before continuing). **Section B: Format hint.** > Explainer: This is a free-form description of how the principles are structured in your file. The skill uses this to reason about cross-references, correction cases, and domain-specific sections. The format is not a schema (the skill is format-tolerant) but a description helps it reason better. Default detection: skim the first 50 lines of the principles file. If it has numbered cross-cutting principles with bold names, "Why:" and "Where:" sections, propose: > "Numbered cross-cutting principles with **bold name**, statement, Why:, and Where: sections. Domain-specific principles under `## Domain-specific principles`. Cross-references between principles by number. Correction cases embedded in `Where:` sections." If the format is simpler (bullets, plain headers), describe what you see and let the user adjust. **Section C: Domain map (optional).** > Explainer: Some principles only apply to specific subsystems (e.g. PRM, Tasks). The domain map tells the skill which directories trigger which principle subsets, so it can pull in domain-specific principles when the topic is in a named domain. If the principles file has a `## Domain-specific principles` section (or similar), propose a mapping by reading the section headings and looking for matching directories under `src/` or similar. Otherwise skip this section entirely. **Section D: Hook integration (optional, opt-in).** > Explainer: By default, you invoke `stay-principled:grill` manually. Hook integration makes other skills (typically `superpowers:brainstorming`) suggest grilling first when this project has principles configured. Three patterns are available; pick zero, one, or multiple. Present the three patterns. The user can decline all of them; the runtime skill works fine without integration. - **Pattern A: CLAUDE.md prose.** Soft, model-driven. A line added to CLAUDE.md telling the model to consider grilling first. - **Pattern B: Hook helper.** Hard, deterministic. A `settings.json` snippet that fires `skill-advice` on every `superpowers:brainstorming` invocation. - **Pattern C: tool-routing rule.** Hard, deterministic. Only offered if `tool-routing` is installed. For each chosen pattern, draft the snippet. See the project [`docs/integration-patterns.md`](../../docs/integration-patterns.md) for the templates. ### 3. Draft and confirm Show the user a draft of: - The contents of `docs/agents/principles.md` - The `### Principles` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited - Pattern A snippet (if chosen): appended to CLAUDE.md as a routing line - Pattern B snippet (if chosen): printed for paste into `settings.json`. Do not auto-write `settings.json`. - Pattern C snippet (if chosen): printed for paste into a tool-routing routes file. Do not auto-write. Let the user edit before writing. ### 4. Write **Pick the file to edit:** - If `CLAUDE.md` exists, edit it. - Else if `AGENTS.md` exists, edit it. - If neither exists, ask the user which one to create. Don't pick for them. Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa). Always edit the one that's already there. If an `## Agent skills` block already exists, add the `### Principles` subsection in-place. Don't append a duplicate. Don't overwrite user edits to surrounding sections. The block: ```markdown ## Agent skills ### Principles [one-line summary of where principles live]. See `docs/agents/principles.md` for format and configuration. The `stay-principled:grill` skill reads from these files. ``` Then write `docs/agents/principles.md` using this template, replacing the file's content if it already exists: ```markdown # Principles configuration ## Files - [path to first principles file] - [path to second, if any] ## Format [user-confirmed format description from Section B] ## Domain map [domain to directory mappings from Section C, or omit if skipped] ## Skip patterns [branch-name or path patterns where principle anchoring should be skipped, or omit] ``` Pattern A/B/C snippets: write Pattern A inline into CLAUDE.md (append a routing line at the end of the agent-skills block). Print Pattern B and Pattern C snippets for the user to paste manually. ### 5. Done Tell the user: 1. Setup is complete. 2. Which files were written. 3. That `stay-principled:grill` will now read from `docs/agents/principles.md`. 4. That re-running this skill is only needed if the file layout changes; manual edits to `docs/agents/principles.md` are fine. If integration patterns were offered, remind the user to paste any Pattern B/C snippets into the appropriate config file.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.