gustavo-meilus/superpipelines / plugins/superpipelines/skills/sk-claude-code-conventions
sk-claude-code-conventions
VerifiedProvides canonical engineering standards for authoring agents, skills, hooks, and pipeline orchestration in Claude Code. Use when authoring or modifying agents, skills, hooks, or pipeline-orchestration artifacts — covers model-tier selection, prompt-cache discipline, frontmatter schemas, and progressive-disclosure rules.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.8 KB |
SKILL.md
View on GitHub---
name: sk-claude-code-conventions
description: Provides canonical engineering standards for authoring agents, skills, hooks, and pipeline orchestration in Claude Code. Use when authoring or modifying agents, skills, hooks, or pipeline-orchestration artifacts — covers model-tier selection, prompt-cache discipline, frontmatter schemas, and progressive-disclosure rules.
user-invocable: false
---
# Claude Code Conventions — Reference
<glossary>
<term name="Adaptive Thinking">Model-driven reasoning scaled by the `effort` parameter.</term>
<term name="Prompt Caching">A mechanism to persist static context (system prompts, skills) to reduce latency and cost.</term>
<term name="Progressive Disclosure">Structuring content into layers (Body → References) to minimize context bloat.</term>
</glossary>
## Model & Reasoning Selection
<model_tier_table>
| Tier | Model ID | Application |
| :--- | :--- | :--- |
| `triage` | `claude-haiku-4-5-20251001` | High-volume, low-latency classification. |
| `fast` | `claude-haiku-4-5-20251001` | Reviews and bounded worker steps. |
| `medium` | `claude-sonnet-4-6` | Default for pipelines, agents, and skills. |
| `deep` | `claude-opus-4-8` | High-complexity architecture or auditing tasks. |
</model_tier_table>
<invariant>
This skill is Claude Code-scoped (Tier 1 only). Concrete model IDs above describe the Tier 1 resolution of the `MODEL_SELECTION: TIER_BASED_RUNTIME_RESOLVED` invariant — i.e., Tier 1's `platform_profile.model_tiers.medium` resolves to `claude-sonnet-4-6`, `.fast`/`.triage` to `claude-haiku-4-5-20251001`, and `.deep` to `claude-opus-4-8`. On other tiers the same `fast`/`deep` slots resolve to that platform's idiomatic models (see `skills/sk-platform-dispatch/profiles/{tier_id}.json`). Per `DEPENDENCY_INVERSION: PROFILE_DRIVEN`, pipeline-architect and other tier-agnostic skills MUST consult `platform_profile.model_tiers` rather than the CC literals shown here. Reasoning scales within-tier via `effort`; tier switches are warranted only when the step category genuinely differs.
</invariant>
## Caching & Context Discipline
<protocol>
### 1. CACHE STABILITY
- **Static First**: Context ordered as System Prompt → Skills → Tools → Conversation History.
- **Invariant Toolsets**: Tool and skill lists must not be mutated mid-session; mutation invalidates the entire prefix.
- **Static Headers**: Dynamic timestamps or mutable data must not appear in the static system prefix.
### 2. CACHE BREAKPOINTS
- Up to 4 `cache_control` breakpoints are supported.
- The final breakpoint belongs on the last block that remains identical across requests.
- Agentic loops use 1-hour TTL to prevent cache expiration between turns.
</protocol>
## Artifact Schemas
### Skill Frontmatter
<invariant>
`SKILL.md` bodies must not exceed 500 lines. Descriptions must use third-person voice and focus strictly on triggering conditions.
</invariant>
```yaml
name: {lowercase-hyphens}
description: {triggering-only, third person}
effort: {low | medium | high | xhigh | max}
disable-model-invocation: {boolean}
user-invocable: {boolean}
```
### Agent Frontmatter
<invariant>
Agent bodies must not exceed 150 lines. Depth belongs in companion `<agent>-references/references/*.md` files.
</invariant>
```yaml
name: {identifier}
description: {action-oriented trigger}
effort: {high for architects, medium for workers}
isolation: worktree
skills: [sk-4d-method, sk-spec-driven-development]
```
<invariant>
Plugin-scope enforcement rule: Claude Code ignores `permissionMode`, `hooks`, and `mcpServers` on subagents loaded from a plugin — only `tools:` and `disallowedTools:` are enforced on that path. Reviewer write-deny for plugin-shipped agents therefore rests entirely on the tool allowlist; `permissionMode` in `agents/*.md` is declarative intent, not a barrier. Project-scope agents (including agents MATERIALIZE writes under `.claude/agents/superpipelines/{P}/`) enforce `permissionMode` normally. No document may claim `permissionMode` enforcement for plugin-shipped agents (auditor BUNDLE-08).
</invariant>
## Progressive Disclosure Checklist
<checklist>
- [ ] `SKILL.md` body ≤500 lines.
- [ ] References are exactly one level deep from `SKILL.md`.
- [ ] References >100 lines include a Table of Contents.
- [ ] Descriptions are third-person and triggering-only.
- [ ] Examples are concrete and specific to the domain.
</checklist>
<invariants>
- `memory: project` must not appear in agent frontmatter.
- All relative paths must be resolved via `${CLAUDE_PLUGIN_ROOT}` or `${CLAUDE_PLUGIN_DATA}`.
- All pipeline state must be persisted to the canonical `pipeline-state.json` location.
</invariants>
## Reference Files
- `sk-pipeline-state/SKILL.md` — State management rules.
- `sk-pipeline-paths/SKILL.md` — Scope-aware path resolution.
- `sk-4d-method/SKILL.md` — Per-invocation wrapper.
- `sk-spec-driven-development/SKILL.md` — SDD protocol.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |