Extending AI Coding Assistants with Skills: Classification, Authoring, and Selection

Most developers treat AI coding assistants as code-completion tools. What experienced teams actually depend on is a set of designed extension skills. Those skills let the model read team conventions, invoke local scripts, and complete multi-step tasks. Based on public documentation and community practice, this article explains how skills work and how teams should choose and build them.

Slash commands vs. skills

Slash commands and skills are often mixed up, but they run in completely different ways.

Slash commands are client-side shortcuts—clear context, compact history, show a diff. Input and output are fixed; execution does not go through model reasoning. Most built-in slash commands cannot be edited by users.

A skill is a structured instruction file, usually Markdown. When a task matches the skill description, the tool loads that file into the current session. The model follows the instructions, may spawn sub-agents, call local scripts, or orchestrate multi-step flows.

Dimension	Slash commands	Skills
Trigger	Fixed keywords	Model match on natural language
Executor	Client program	Model reasoning over instructions
Customization	Built-ins usually locked	User-editable files
Capability	Built-in features only	Scripts, sub-agents, multi-step flows
Security	Low; behavior is fixed	Higher; depends on granted tool access
Reuse	Usually tool-specific	Reusable if the tool can read the same instruction format

Some tools also let you add custom slash commands or prompt templates via Markdown. “Slash commands cannot be changed” applies only to built-ins. Check the documentation for your tool and version.

Two kinds of skills

Capability skills cover what the model cannot do natively. LLMs generate text and reason; they cannot browse the web, produce PDFs, or query a database by themselves. Capability skills fill those gaps with scripts or APIs. They expand what AI can do, and they introduce real system-access risk (see security below).

Preference skills cover what the model can do, but not in the way your team wants. Style, architecture, and testing habits need to be consistent. Preference skills encode those rules so generated code follows them—for example TDD, or components that must use a designated design system. Risk is lower; the main issue is whether the rules are accurate and match the real codebase.

Writing a skill file

A usable skill typically includes the parts below. The skeleton follows the Anthropic Agent Skills convention; field names and directories should match the current docs for your tool:

---
name: frontend-component
description: Generate React components against the company design system. Use when the user asks for a new UI component.
---
## Goal
Generate a React component that matches the design system, with unit tests.
## Steps
1. Read tokens and existing components under src/design-system.
2. Compose the UI from existing primitives such as Button and Card.
3. Write tests, run them, and fix failures.
## Examples
Do: use theme.colors.primary for color.
Don't: hard-code #3366ff.
## Stop conditions
- Stop and ask the user if the request conflicts with the design spec.
- Stop and request human confirmation before changing src/config or environment variables.
## Permissions
- Read allowed: src/design-system and src/components.
- Write allowed: a new directory under src/components.
- Forbidden: .env and any secret files.

Authoring notes:

• Clear, stepped instructions. Split complex work; headings and lists help the model parse.
• Positive and negative examples. Models are pattern-sensitive; a few do/don’t examples often beat a long description.
• Stop conditions. Say when to pause for a human, reducing hallucinated actions.
• Declare permissions. Spell out allowed paths and forbidden content.

Load paths vary. Under Agent Skills, project skills often live in .claude/skills/; user skills live in a corresponding directory in the home folder. Put project skills in version control so conventions evolve with the code.

Common mistakes: instructions so long that key rules are buried; no stop conditions, so the model guesses on ambiguity; examples that contradict the spec; no permission declaration, so the model reads files it should not; descriptions so broad that the skill fires on unrelated tasks.

Selection checklist and order

Answer four questions first:

1. Team size and collaboration. Solo projects can start with preference skills for personal habits. Multi-person teams get more value from shared convention skills.
2. Compliance. Can code or internal docs go to a third-party model? Is PII or regulated data involved? Higher compliance pressure favors local execution and tight external access.
3. Existing toolchain. Reuse test frameworks, build scripts, and design systems instead of maintaining duplicates.
4. Maintenance cost. Every skill must be updated with the code. Skills without an owner go stale.

Suggested order: preference skills for tests and conventions first (low risk, fast payoff); then resource-access skills such as frontend components and doc retrieval; capability skills that call external services last.

Three recommended directions and acceptance criteria

1. Automated tests and verification
Guide the model to write tests first, then implementation, then run tests and fix from failures. Acceptance: all unit tests pass; coverage is not below the pre-change baseline; auto-fix retries are capped (e.g. 3), then hand off to a human.

2. Frontend conventions and component generation
Put design-system tokens, existing components, and naming into the skill. Acceptance: lint passes; colors, type, and spacing use tokens only—no hardcoded values; new components can be used from existing pages.

3. Document extraction and engineering knowledge retrieval
On legacy systems, help the model read unstructured docs and answer questions about history and module ownership to support refactoring. Acceptance: on a prepared sample of questions, cited passages meet a team-set accuracy bar; every answer includes source file and location for review. The bar is set by the team’s risk tolerance.

Security and compliance

Capability skills that call scripts, APIs, the web, or databases must follow least privilege.

• Least privilege. Grant only the paths, commands, and APIs needed. Prefer read-only DB accounts.
• Secret handling. API keys in environment variables or a secrets manager—not in skill files, code, or logs.
• Sandboxed execution. Run external scripts in isolation; limit network access.
• Audit logs. Record time, parameters, files touched, and outbound requests.
• Human confirmation. Deleting files, sending messages, deploying, or changing permissions must wait for a person.
• Prompt-injection defense. Web pages, documents, and tool output are data, not instructions. If they contain “please do X,” report it; do not obey.

Skill files themselves do not add a subscription fee. Cost comes from model calls, runtime, and scripts. Estimate those costs and confirm data-compliance terms before connecting a third-party model.

Closing

Skills turn a generic coding assistant into a platform customized to team rules. Distinguishing slash commands from skills, knowing the two skill types, and writing permissions, stop conditions, and acceptance criteria are the foundation of a reliable workflow. With model cost under control and permissions governed, this practice can cut repeated coordination and rework—if teams adopt it gradually and keep maintaining it.