agentsop-conventions-pinning
SOP for writing, loading, and evolving a project-level convention file (CONVENTIONS.md / CLAUDE.md / .cursor/rules / .clinerules / AGENTS.md) so that a coder-agent reliably respects your codebase's style choices every session. Tool-agnostic; covers the four load mechanics (read-only attachment, ancestor-walk auto-load, glob-scoped rules, agent backstory) and the conflict resolution between pinned conventions and the existing code.
npx skills add agentsope/SkillAlchemy --skill agentsop-conventions-pinning --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Pin and evolve a project-level conventions file (CONVENTIONS.md / CLAUDE.md / .cursor/rules / .clinerules / AGENTS.md) so coder-agents respect a codebase's style choices each session. Covers four load mechanics (read-only attachment, ancestor-walk auto-load, glob-scoped rules, agent backstory) and how to resolve conflicts between pinned conventions and existing code.
How it works
- The skill defines activation triggers and when to use conventions (e.g., recurring style questions, repeated corrections, onboarding, tool-switching).
- It prescribes a concrete workflow: Phase 1 Write a concise conventions set (5–15 bullets); Phase 2 Load the conventions with the chosen tool’s mechanism (read-only attach, ancestor-walk auto-load, glob-scoped rules, or agent backstory) and verify loading via tool-specific commands (e.g., memory view, side panel). Phase 3 Enforce by testing a specific, verifiable rule (e.g., ensure an HTTP call uses httpx). Phase 4 Evolve by adding or deleting rules based on drift or enforcement, with criteria for splitting rules into glob-scoped sets when needed.
- It provides templates and location advice for canonical placement of the conventions file per tool (e.g., CLAUDE.md for Claude Code, CONVENTIONS.md for Aider, and so on).
- It notes conflict precedence and two patterns for resolving drift: convention wins (refactor) or code wins (archive rule).
When to use it
- Any project you (or your agent) will return to more than once
- The same correction has been typed in chat more than twice
- Code review (human or LLM) keeps catching style violations the agent should know
- Onboarding a new agent / new teammate; they need the project's tacit rules in writing
- You switch coder-tools and want one canonical style source across Aider, Claude Code, Cursor, Cline
What it can touch
- Tools: claude-code
- It specifies loading and interaction via the chosen tool's conventions (CLAUDE.md for Claude Code; CONVENTIONS.md for Aider; .cursor/rules for Cursor; .clinerules for Cline; AGENTS.md for multi-tool setups).
Caveats
- It emphasizes that conventions are guidance, not hard enforcement; hard enforcement should use hooks/CI when needed.
- It warns about potential arbitrary picks when two rules conflict and encourages periodic cleanup to remove outdated or conflicting instructions.
- It recommends keeping the 200-line guidance budget per CLAUDE.md and similar constraints for other tools to maintain context efficiency.
# Conventions Pinning — Writing a Style Guide Your Coder-Agent Will Actually Read > One line: a conventions file is **the system prompt of your codebase**. Treat it like a system prompt, not like a README. Anti-patterns: writing prose, narrating history, marketing the project. Patterns: command-first, verifiable, "prefer X over Y", < 200 lines. --- ## 1. 何时激活 (When to Activate) ### 1.1 Direct triggers - The user (human or upstream agent) asks "how do I make Claude/Cursor/Cline/Aider respect our style?". - The same correction has been typed in chat ≥ 2 times this week ("use httpx not requests", "add type hints", "no comments on every line"). Claude Code's docs codify this rule: *"Add to it when Claude makes the same mistake a second time."* [code.claude.com/docs/en/memory] - A new project is past the "first 2 modules" phase — there are now style choices implicit in the code that an outsider (or fresh-context agent) can't see. - The team is switching coder-tools (Aider → Claude Code, or adding Cursor) and conventions are scattered in chat history. - An AI code review caught the same anti-pattern twice. ### 1.2 Reverse triggers (skip) - **One-off / throwaway scripts**. The write-cost
- 1. 何时激活 (When to Activate)
- 1.1 Direct triggers
- 1.2 Reverse triggers (skip)
- 1.3 Mental check
- 2. 核心心智模型 (Mental Model)
- 2.1 Convention as compile-time, code-review as runtime
- 2.2 The four load mechanics across the ecosystem
- 2.3 Three rules for what goes in (and what doesn't)
- 2.4 Size budget: 200 lines, hard
- 2.5 The conflict precedence rule
- 3. SOP 工作流 (Standard Operating Procedure)
- Phase 0: Decide whether to write one at all
- Phase 1: Write — the first cut
- Phase 2: Load — make sure the agent actually reads it
What does the agentsop-conventions-pinning skill do?
SOP for writing, loading, and evolving a project-level convention file (CONVENTIONS.md / CLAUDE.md / .cursor/rules / .clinerules / AGENTS.md) so that a coder-agent reliably respects your codebase's style choices every session. Tool-agnostic; covers the four load mechanics (read-only attachment, ancestor-walk auto-load, glob-scoped rules, agent backstory) and the conflict resolution between pinned conventions and the existing code.
How do I install it?
Run `npx skills add agentsope/SkillAlchemy --skill agentsop-conventions-pinning --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From agentsope/SkillAlchemy, a repository with 255 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.