Skip to content
Skills Library
AI & agents · Planning

sp-coding-agent

/sp-coding-agent

Use when a coding task is vague or under-specified. Extracts missing context across 9 code-native categories before the agent executes file changes. Designed for OpenAI Codex, Anthropic Claude Code, and Google Gemini Code Assist.

Licence
Apache-2.0
Last repository change
25.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when a coding task is vague or under-specified. Extracts missing context across 9 code-native categories before the agent executes file changes. Designed for OpenAI Codex, Anthropic Claude Code, and Google Gemini Code Assist.

Original author description

Use when a coding task is vague or under-specified. Extracts missing context across 9 code-native categories before the agent executes file changes. Designed for OpenAI Codex, Anthropic Claude Code, and Google Gemini Code Assist.

How it works

  1. How to Load This Skill
  2. Reference Files
  3. When to Use This Skill
  4. How It Works
  5. The 9 Code-Native Categories
  6. Coding Task Classification
  7. Task Taxonomy Mapping (Generic → Coding)
  8. Execution Gates (Hard Stops)
  9. Worked Example: Bug Fix Context Extraction
  10. Key Differences from Chatbot Versions
Original SKILL.md headings · 235 lines, 1,871 words
SKILL.md preview
---
name: sp-coding-agent
description: Use when a coding task is vague or under-specified. Extracts missing context across 9 code-native categories before the agent executes file changes. Designed for OpenAI Codex, Anthropic Claude Code, and Google Gemini Code Assist.
---

# SMART POLE Coding Agent Skill

This Skill implements the **SMART POLE** framework adapted for **AI Coding Agents**. Unlike the chatbot versions (Instructor/Enforcer), this skill operates on **codebases** — scanning project files, extracting context automatically, and ensuring the agent has enough information before writing code.

---

## How to Load This Skill

1. **Set system prompt**: Load `references/system-prompt.md` as the agent's system prompt (e.g., paste into `AGENTS.md`, `.claude/system_prompt.md`, or the agent's system role configuration).
2. **Provide reference files**: Make `references/logic.md`, `references/overlap-rules.md`, and `references/coding-agent-categories.md` available in the agent's context or knowledge base.
3. **Invoke**: Give the agent a vague or specific coding task. The agent will ORIENT (scan the codebase), CLASSIFY the task type, EXTRACT SP-categories, and check execution gates before touching any file.

---

## Reference Files

| File | Purpose |
|------|---------|
| `references/system-prompt.md` | 🔴 **Required** — Full Coding Agent system prompt (v4.0). Load as the agent's system instructions. |
| `references/logic.md` | Framework logic: category definitions, weighted scoring, task-type classification, generic-to-coding task mapping. |
| `references/overlap-rules.md` | Atom overlap rules, conflict detection, Functional Gravity principle, and the One Atom One Slot rule. |
| `references/coding-agent-categories.md` | Code-native sub-dimensions for all 9 SP-categories with auto-detection sources and hard-stop gate definitions. |

---

## When to Use This Skill

- A user gives a vague coding task ("fix the login bug", "add pagination")
- Before an agent starts multi-file code changes
- When a task involves unfamiliar parts of a codebase
- Migration or refactoring tasks where scope control is critical

## How It Works

1. **ORIENT**: Agent scans project root (`README.md`, `AGENTS.md`, `package.json`, `Dockerfile`, etc.)
2. **CLASSIFY**: Determine task type (Bug Fix / Feature / Refactor / Migration / Infra)
3. **EXTRACT**: Map request to 9 code-native SP-categories
4. **DETECT FLAWS**: Identify missing context, overlaps, and conflicts; ask user if critical
5. **PLAN**: Create implementation plan with file-level scope
6. **EXECUTE**: Apply file changes within approved scope
7. **VERIFY**: Run tests, lint, type-check; self-heal on failures

## The 9 Code-Native Categories

| Abbrev | Category | Code Meaning | Priority |
| --- | --- | --- | --- |
| **S** | Style | Code standards, linting, architecture pattern | 🟢 Auto-detect |
| **M** | Mastery | Developer expertise level — split into Domain vs Task (see below) | 🟡 Contextualizer |
| **A** | Aim | Definition of Done, acceptance criteria, success metric | 🔴 **CORE** |
| **R** | Resource | Allowed/forbidden deps, API quotas, team contacts, internal docs | 🟡 Contextualizer |
| **T** | Time | Deadline, urgency level (hotfix vs long-term), sprint constraints | 🟢 Accelerator |
| **P** | People | Team conventions, reviewer persona, implicit values & preferences | 🟡 Contextualizer |
| **O** | Outline | Authorized file scope, folder boundaries, what NOT to touch | 🔴 **CORE** |
| **L** | Locale | Runtime ecosystem, language/framework version, legal/infra constraints | 🟡/🔴 **CONDITIONAL** |
| **E** | Example | Reference code snippets, similar PRs, anti-pattern stories | 🟡/🟢 **CONDITIONAL** |

---

### Category Deep-Dives (SP-Flaw Prevention)

#### ⏱️ T — Time: Urgency Only, Not Quality

**T answers**: "How much time do I have?" — deadline, sprint slot, hotfix vs planned refactor.

> ⚠️ **T-Flaw (Category Overlap)**: Do NOT put acceptance criteria or content depth requirements inside T.
>
> - ❌ Wrong: `T: "Must be thorough enough to not need follow-up"` ← this is an **A-atom**
> - ✅ Right: `T: "Hotfix — must ship in 2 hours"` / `T: "Non-urgent — next sprint"`

Quality gates and success criteria belong in **Aim (A)** or **Outline (O)**, not Time.

---

#### 👥 P — People: Make Implicit Traits Explicit

**P answers**: "Who is involved and what are their hidden assumptions?"

Beyond team conventions, always surface:

- **Reviewer Persona**: Does the reviewer prioritize security over speed? Hate over-engineered abstractions?
- **Implicit Values**: Prefers functional style? Allergic to ORMs? Values minimal diffs?
- **Psychological traits**: Team culture (consensus-driven vs individual autonomy), risk tolerance

> ⚠️ **P-Flaw (Implicit People)**: Do NOT leave personality traits and values implicit — the agent will guess wrong.
>
> - ❌ Wrong: Omitting that the team hates `any` types in TypeScript
> - ✅ Right: `P: "Reviewer flags every use of 'any' in TypeScript — use strict types always"`

---

#### 🎓 M — Mastery: Always Split Domain vs Task

**M answers**: "What does the developer know — and in which dimension?"

Always decompose Mastery into **two parts**:

| Dimension | Meaning | Example |
|-----------|---------|---------|
| **M-Domain** | Expertise in tech stack / role | Senior React, Junior DevOps |
| **M-Task** | Experience with this specific task type | Never integrated Stripe before, First time with WebSocket |

> ⚠️ **M-Flaw (Mastery Scope)**: Missing the gap between Domain and Task mastery causes the agent to pitch solutions that are technically fluent but practically inappropriate.
>
> - ❌ Wrong: `M: "Senior Developer"` ← domain only, no task dimension
> - ✅ Right: `M-Domain: "Senior React" | M-Task: "Novice — first time implementing OAuth2 flow"` → agent uses familiar React patterns but explains OAuth2 step-by-step

---

#### 🧰 R — Resource: Tools + People + Data

**R answers**: "What weapons do I have — and what is forbidden?"

Resource includes **three dimensions**, not just software:

| Dimension | Examples |
|-----------|---------|
| **Tools** | Allowed libs/frameworks, CI/CD pipeline, dev environment |
| **People / Network** | Team members who can review, external consultants, on-call SMEs |
| **Data / Docs** | Internal wikis, API docs, log access (`/var/log/auth.log`), Sentry |

> ⚠️ **R-Flaw (Resource Underutilization)**: Listing only software tools leaves the agent unable to suggest "ask the security team" or "check the Confluence runbook."
>
> - ❌ Wrong: `R: "Jira, Notion"` ← tools only
> - ✅ Right: `R-Tools: "Jira" | R-Network: "Security team available for review" | R-Data: "Sentry logs + Redis CLI access"`

Also supply **Negative Atoms** (what is forbidden):
> `R-Forbidden: "No new npm deps without approval, no changes to DB schema"`

---

#### 📌 E — Example: The Anchor Atom

**E answers**: "What should the output look like — concretely?"

In coding context, a **Gold Standard E-atom** is a matched pair:

| E-atom Type | What it looks like |
|-------------|-------------------|
| **Code snippet** | Before/after code block showing the pattern to follow |
| **Similar PR** | Link or description of a past PR that solved a comparable bug |
| **Input/Output pair** | Expected test case: input state → expected behavior |
| **Anti-example (Story)** | "Last time we did X this way, it broke Y — avoid this pattern" |

> ⚠️ **E-Flaw (Missing Anchor)**: Without an Example atom, the agent mimics its training data defaults, not your codebase conventions.
>
> - ❌ Weak: `E: "Make it look clean"` ← too vague, gives agent no anchor
> - ✅ Gold: `E: "Follow the pattern in auth_service.py:L45–80 — token invalidation before session update"` or `E: "This Sentry trace shows the failure chain: A→B→C"`

Always ask: *"Is there a similar PR, a log trace, or a code section I want the agent to mimic?"*

---

### Auto-Extraction Sources

| Source File | SP-Categories Extracted |
|-------------|------------------------|
| `.eslintrc` / `ruff.toml` | **S** (Style) |
| `package.json` / `pyproject.toml` | **R** (Resource), **L** (Locale) |
| `Dockerfile` / `docker-compose.yml` | **L** (Locale), **R** (Resource) |
| `AGENTS.md` / `SKILL.md` | **P** (People), **S** (Style) |
| CI/CD configs (`.github/workflows/`) | **R** (Resource), **A** (Aim quality gates) |

## Coding Task Classification

| Task Type | Primary SP-cats | Agent Behavior |
|-----------|----------------|----------------|
| Bug Fix | A, E, O | Minimal change + regression test |
| Feature | A, O, R | Plan → implement → test |
| Refactor | O, E, P | Preserve behavior, improve structure |
| Migration | L, R, T | Incremental, backward compatible |
| Infra | L, R, A | Infrastructure as Code, idempotent |

## Task Taxonomy Mapping (Generic → Coding)

Use this mapping to bridge generic SMART POLE task types in `references/logic.md` with coding-agent task types.

| Generic Task Type (`references/logic.md`) | Coding Task Type(s) | Default Interpretation |
|-----------|----------------|----------------|
| Deterministic | Bug Fix, Refactor | Behavior is constrained; prioritize reproducibility and regression tests |
| Generative | Feature | New capability; prioritize clear DoD and explicit scope boundaries |
| Advisory | Refactor, Migration, Infra | Architecture/process guidance; convert advice into testable acceptance criteria before coding |
| Discovery | Feature (spike), Migration (assessment) | Exploration is allowed, but execution stays minimal and reversible |
| Compliance | Infra, Migration, Bug Fix | Regulatory/security constraints are first-class acceptance criteria |

## Execution Gates (Hard Stops)

Do not execute code changes until all hard-stop gates pass:

1. **Gate A (Aim)**: At least one testable acceptance criterion exists.
2. **Gate O (Outline)**: Authorized scope is explicit (or defaults to minimal scope) and forbidden scope is respected.
3. **Gate Conflict**: All `SP-conflict` items are resolved by user decision.
4. **Gate Overlap**: Apply `One Atom, One Slot` from `references/overlap-rules.md`; no double-counted atoms.
5. **Gate Score**: Weighted readiness score is **>= 67%** of the applicable max score (per `references/logic.md` task-type weighting).

If any gate fails:

- Stop before `EXECUTE`
- Ask targeted clarification questions
- Re-plan only after user confirmation

## Worked Example: Bug Fix Context Extraction

**User request**: `"Fix the login bug — users can't login after password reset"`

| SP-cat | Atom | Why here, not elsewhere |
|--------|------|------------------------|
| **S** | `Auto-detect from .eslintrc` | Style from project config |
| **M-Domain** | `Senior Backend Developer` | Tech stack expertise |
| **M-Task** | `Novice — unfamiliar with this legacy auth system` | Task-specific gap |
| **A** | `Login succeeds with new password; old session invalidated; unit tests pass` | Success criteria → **not** T |
| **R-Tools** | `Redis CLI access, Sentry error traces` | Concrete toolbox |
| **R-Network** | `Security team available on Slack for review` | Human resource |
| **T** | `Hotfix — must ship within 2 hours` | Urgency only — **not** quality |
| **P** | `Reviewer prioritizes security over speed; avoids over-optimization at hotfix stage` | Explicit reviewer values |
| **O** | `Only modify auth_service.py and password_controller.py` | Scope boundary |
| **L** | `Python 3.11, Django 4.2, Redis 7` | Runtime ecosystem |
| **E** | `Sentry trace shows: PasswordReset→UpdateDB→[FAIL: session not invalidated]→Login` | Concrete anchor |

> 🔍 **SP-flaw check**: "Write unit tests" is an **A-atom** (acceptance criterion), NOT a **T-atom** (time/urgency).

## Key Differences from Chatbot Versions

| Aspect | Instructor/Enforcer | Coding Agent |
|--------|-------------------|--------------| 
| Output | Master Prompt text | Working code + passing tests |
| Reasoning visibility | Prompt-analysis oriented | Concise decisions tied to files/tests (no explicit CoT requirement) |
| Verification | User reviews prompt | Agent runs tests automatically |
| Context | Conversation only | Codebase + configs + file system |
| Self-healing | N/A | Auto-fix on test failure (max 3 attempts) |

## Optional: Integration with Other Skills

This skill works best as a **pre-flight layer** in any coding agent workflow, ensuring sufficient context before execution begins. Pair with project-specific `AGENTS.md` or workflow files.
Files in this package (7)
  • SKILL.md 12 KB
  • SKILL.md.orig 6 KB
  • agents/openai.yaml 1 KB
  • references/coding-agent-categories.md 10 KB
  • references/logic.md 13 KB
  • references/overlap-rules.md 12 KB
  • references/system-prompt.md 14 KB

Versions

The database has no other skills named sp-coding-agent.

Database snapshot: 13.11.2026 · package version f0db86553f42 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100dev-swarm-install-ai-code-agent
    Install AI code agent CLI tools including claude-code, gemini-cli, codex, and github copilot-cli. Use when setting up AI coding assistants or when the user asks to install an AI code agent.
  • 100coding-agent
    Run Codex CLI, Claude Code, or other coding agents as background processes for programmatic control. Use when a user asks to run a coding agent, delegate a task to another AI, spawn a sub-agent, run Claude Code in the background, or orchestrate multiple coding agents on separate tasks.
  • 100bb-install-and-connect
    Use when bb is installed but the agent has no bb tools, or when wiring bb into Claude Code, Cursor, VS Code, Codex, Gemini, opencode or another agent host.
  • 90kit-optimize-context
    Analyze always-on agent context across coding hosts (Cursor, Claude Code, Codex, Gemini CLI, etc.) and suggest token reductions. Use when sessions feel heavy before you type anything.
  • 100code-mate-gemini
    Run Gemini CLI non-interactively for coding tasks. Use when the user asks to delegate work to Gemini.
  • 95ai-coding-agents
    Comprehensive guide for using Codex CLI (OpenAI) and Claude Code CLI (Anthropic) - AI-powered coding agents. Use when orchestrating CLI commands, automating tasks, configuring agents, or troubleshooting issues.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.